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HINK ALL '040 
ACCELERATORS ARE THE SAME? 

THINK AGAIN! 



As a high power Amiga 30003000T 
user you need a 68040 accelerator 
hoard lor one reason . . . and one 
reason only ...SPEED! 

Ami once you knovi what nukes one 
6SQ40aiceleratnr better tlun another. 
the (inly Kurd you'll want is the 
G-FORCE 040 from GVP 

WATCH 001 FOR SLOW DRAM BOTTLENECKS 

)< - .ili toQ40CFU sarc created equal 
bur this doesn't mean ihat all accelerator 
boards allow ur A3000 lo nuke the 

4bost of the 68040 CPU's incredible 

"performance 

The AKKH) wjk designed io work with 
low-cost, 80ns DRAM | memory! tech- 
nology. As a result, anytime the '040 
CPU accesses the A.iOOO motherboard. 
memory lots oi CPU waiuaates arc 
introduced and all the reasons you 
hnu>Jit your accelerator literally come 
to a screeching halt! 
Not true for the G-FORCE 040 

SOLUTION: THE G-FORCE 040*1 f AST, 40ns, 
ON BOARD DRAM 

To eliminate this memory access bottle- 
neck, we designed a special 1MB, 32-bit 
wide, non-multiplexed, SIMM module 
using 40ns DRAMs (yes, iotty niino- 
secoadsl] This revolutionary memory 
module allows the G-FORCE 040 to be 
populated wuh up to 8MB ol statc-oi-thc- 
art, high performance, onboard DRAM 
Think ol rhi~ as I Kiam 8MB cache which 
lets the 040 CPU race along at the top 
performance Speeds you paid lor 

SHOP SMART: COMPARE THESE G-FORCE 040 
SPECS TO ANY OTHER TWO ACCELERATOR 

► 68040 CPU running at l^Mh; provid- 
ing 22 MIPS and 175 MaOPS! 
NOTE. The 6&040 imoiportitf 
MMU, FPU and icpainw ^Kfi data and 
■ ■ Uon caches oa a single chip. 




^ to 8MB of onboard, | . 

40ns, non-multiplexed, DRAM. 
Fully autoconligured, user-install- 
able SIMM modules lets you expand 
your A3000 to 24MB! 
fe> DRAM controller design hilly supports 
the hs040 CPU'* burst memory access 
mode. 

»> Full DMA Diieci Memory Access 
to/from the onboard DRAM by any 
A3000 pcnpheral |e.g the A.JOOO's built 

in hard disk controller), 

fe> Asynchronous design allow 
the 68040 to run at clock 
Speeds independent oi the 
A3000 motherboard speed. 
Allows easy upgrade to .J.JMhz 
68040, over 15 J MIPS! I when available 
from Motorola. 

b> Hardware support lor allowing V2 
Kickstan ROM to be copied into jnd 
mirrored by the high performance on- 
board DRAM. Its like caching the entire 
operating system! 

k> Software switchahk 68030 "tailback' 
mode for full backward compatibility 
wuh the AJOOO's native 68030 CPU. 
b> Incorporates CVl's proven quality, 
experience and leadership in Amiga 
leratoi products. 

TRY A RAM DISK PERFORMANCE TEST AN0 SE 
FOR YOURSELF HOW THE C FORCE 040 OUT 
PERFORMS IHE COMPETITION 

ur dealer to run any RAM disk" per 
tormancc test and see the G-FORCE 040 s 
amazing powers m action. 
So now that you know the facts, order 
vour G-FORCE 040 today. After all. the 
only reason why you need an '040 accel- 
erator is SPEED] 
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printf ("Hello") ; 



// 



print "Hello 



JSR printMsg 



say "Hello" 



writeln( "Hello") 



HIiatcAor lail^oa^r you speak. \< "s I 1 ( II 

provides a platform lor both gaining insiulil 

mid sharing information on iis most 

innovative implrmciilalioii for ihc Amif*a. 

\\U\ not see if your lairsi programming 

riidoavor can help a follow \miun user 

expand upon his or her vocabulary? To be 

considered for publication in \i *s I I < II. 

submit voiir technical IS oriented article 

(both hard <*«»p\ & disk) to: 



\c S rECH submissions 
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Startup-Sequence 



Its Official— AmigaDOS 2.04! 

Move over AmigaDOS 1.3... AmigaDOS 2.04 is officially 
here! The OS code has been frozen. The final release version of 
AmigaDOS release 2 is 2.04 with Kickstart v37.175, and Work- 
bench v37.67. These are the OS versions that are being put into 
ROM in the new machines and the Enhancer Kit (upgrade for the 
A5O0/2OO0). 

Easy Upgrades 

Upgrading Amiga 500s and 2000s will be accomplished via 
the 2.04 Enhancer Kit. which will be available through the autho- 
rized dealer channel. This will be a ROM and software upgrade. 
Once the new 2.04 ROMs are in, say goodbye to AmigaDOS 1.3, 
forever. However, there are several third parties that are develop- 
ing, or have developed ROM Towers (switches) for the A500/ 
2000. These ROM Towers hold both 1 .3 and 2.04 KickStart ROMs 
and allow selection of the boot ROM via an externally mounted 
switch. Add a little intelligence to your startup sequence, and 
presto! Dualpersonality! Any side effects? Hmmm.. It's tooearly 
to say, but there is at least one potential problem: AmigaDOS 1 .3 
does not recognize AmigaDOS 2.04 hard links. These will look 
like empty files under 1.3. If anything, these will cause • little (or 
lots) of confusion. Just be cautious... 

A3000-I Want My ROM 

What about an upgrade (or the original Amiga 3000 with 
the SuperKickstart? Sources at Commodore say that a free 2.04 
upgrade will be made available through the dealer channel. This 
will be a five disk sofluwt upgrade (3000 Install, Workbench, 
Extras, AmigaFonts, and KickStart.) Dealers are authorized to 
charge a nominal copying fee for the disks. Will there be a 2.04 
ROM upgrade /system trade-in for the SuperKickstart Amiga 
3000s? At press time thedetailsare unspecified, but there isa plan 
on the table. Ask you dealer for more specific information. 

What about running AmigaDOS 1 .3 on an A3000 with 2.04 
in ROM? You can't ..right now. The A3000 uses two 256K ROMs 
as opposed to a single 512K ROM on the A500/2000. It's this 
reason, plus a hundred other engineering and legal reasons, that 
you won't see an A3000 ROM Tower switch. However, I'm sure 
that some bright entrepreneur/ developer will come up with a 
way (i.e. marketable product) to boot AmigaDOS 1 .3 on an A3000 
with 2.04 in ROM. 



What's your best bet on upgrading a SuperKickstart A3000 
to AmigaDOS 2.04? If you haw to run AmigaDOS 1 .3, then stay 
with a software upgrade — at least until there is another way to 
run 1 .3 on a 2.04 machine. If you area developer, then its probably 
a good idea to stay with the SuperKickstart so you can continue 
to easily get and install system software upgrades. Go with the 
hardware upgrade if you need to use a 68040 CPU in your A3000. 
The new ROMs fixed cache bugs and added OS cache calls. Also, 
it is rumored that some SCSI devices do not like to see the old 
1 .4B5 ROMs. In these cases, the 2.04 ROM are required. Take your 
pick. 

Finally, starting with AmigaDOS 2.04, all new A3000s will 
come with AmigaDOS 2.04 in ROM. 

Looking to the future... 

Next step AmigaStep? 

One of the better applications bundled with the powerful 
UNIX-based NeXT™ workstations is its extremely powerful 
application-builder NeXTStep™. NeXTStep is an extremely in- 
tuitive, easy-to-use, yet incredibly powerful GUI/application 
builder, which puts the power of real programming into the 
hands of the power user. NeXTStep is not an every man'ssolution 
to programming, but it does open up programming to the ad- 
vanced user, who has the mindset to program, but can't get over 
the complexities of programming the GUI at the medium-to-low 
level. NeXTStep can also be used in a lower-level capacity to 
develop commercial-quality software. 

Rumor has it that Commodore is actively working on an 
application builder that will be NeXTStep and more! This versa- 
tile and powerful application builder will be able to handle all 
aspects of the Amiga GUI, ARexx, IDCMP, font sensitivity, and 
more. When can we expect to see this programming marvel? No 
one's talking, but a good guess says that they'll have it in beta 
sometime during the first quarter of '92. 1 can hardly wait... 




Ernest P. Viveiros, Jr. 
Technical Coordinator 
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Build A SCSI Interface for Your 
Amiga 500/1000 byPavi H^r 



CAUl ION: Be careful when attempting to builA 1 t haul ware projects to vour 

computet Always Check your work twice before attaching the prelect to wur computer 
Att>ithinen Home-built project to your Amiga may tviil iteuurranty PiM Pub! 
hu. lis agents, or the author. i> not ttspeit si ble for any faulting damages from (Ml 
care and common tease 



are like many Amiga users, you spend entirely loo 
much time swapping disks and get bored waiting for your icons 
to display and your programs to load. Perhaps it is time to add a 
hard drive. The first step in adding a hard drive is the interlace 
between the computer and the drive. Fbf the Amiga, thedefacto 
standard is SCSI (Small Computer System Interlace). Spartan is a 
build-it-yourselfSCSl hard drive interface lor the A ringa 300 and 
1000. Using CPU (non-DMA) da tatransii-r>. Spartan is capable of 
data transfer rates of well over 300K per second— more than 
adequate for the average Amiga user Spartan is 100% compatible 

With all Amiga software, in. hiding popular hard drive utilities 

such as Quarterbai k. 

Spartan supports all standard SCSI hard drives, removable 
mediaSC SIdrivessuchastheSyQuest,andeventiieotdiBMtvpe 

ST-506/41 2 drives (see Adaptec Sidebar). Drives can be assigned 
to seven different SCSI addresses, and up to fourteen hard drives 
can he controlled. 

Physically, the Spartan SCSI interlace consists of a small 
circuit board connected to the expansion bus of the Amiga. Using 
the powerful AM5380SCSI control IC, two standard ni. chips, 
and a few capacitors and resist, its, ilu- interlace gives your Amiga 
the ability to communicate with standard SCSI drives. The inter- 
lace address in memory is selectable to avoid conflict with ex- 
pansion memory or other add-on hardware To remain inex- 
pensive and to keep the circuit simple, the Spartan interface does 
not support autoconliguration or autobooting. 

The Spartan device driver is ,i tiny 2048-bytc tile which is 
loaded via the MOUNT command, and a properly edited 
mountlist. I.ow-level format routinesareprovided torSCSIdrives. 
and lor Adaptec controllers Also included is the 'C source code 
the the love-level format routines to allow modification forsup- 
port of non-standard SCSI drives, or control of other types of SCSI 
dev ices. 



Addressing 

The Spartan interlace is what is known asa memory mapped 
device. This deviates from the AutoConfig method utilized by 
man v dev ices on the Amiga. AutoConfig looks for an unused area 
in memory, and then assigns that address to the hardware. Due 
to the simplicity of the spartan circuit design, we must do the job 
of locating a safe area in memory ourselves. As Spartan decodes 
memory in o-IK blocks, the safe area to which the interface is 
addressed will be refered to by it's "base address." The base 
address is the high byte of the actual address. As an example, if 
the address is 2FFFFF. then the base address is 21 

There are two areas in the Amiga's memory map which are 
good candidates for locating Spartan. First, the area from F00000 
to F80000 is unused by the Amiga operating system and makes 17 
(address F70O00) a perfect base address for your interlace. How- 
ev er, if you have an Amiga 500 expansion memory cartridge such 
as Ad Ram 540 or similar units with more than 500K of expansion, 
you may not be able to use this address. This is because thev 
remap this area for expansion RAM. The normal one half MB 
A501 or A50I clone expansions will NOT interfere with this 
address. If you are in doubt, refer the the documentation that 
came with your expansion as to where it installs memory. 

It v.hi are unable to locate your interface at base address F7, 
then you must locate it between 200000 and 8FFFFF. This area ts 
normally used for expansion memory, however, unless you have 
a full 8MB, there will be room to address the interface. The 
documentation which came with your memory expansion should 
allow you to locate an unused area within this range. For ex- 
ample, if your expansion memory is: 



Start 




End 


200000 


10 


27FFF 


400000 


to 


47FFF 


800000 


to 


87FFF 



then a base address from 28 to 3F and from 48 to 7F would be 
valid. 
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Regardless of whether your base address is F7 or elsewhere 
in the memory map, nolo the address, as it will be used in 
configuring bofh your hardware and software 

BuMngtliehtierface 

By tar the easiest and most reliable method of building the 

interface is to obtain the etched and drilled circuit boa rdavaUabte 
from the author. If you wish to etch your own board, the pattern 
isprovided in Figure 1. If you wish to build usinganother method 
of construction, see Figure 2 for the schematic. A carefully built 
wire wrapped circuit should have no problems if you keep wire 
lengths to a reasonable minimum The following assembly dis- 
< usskm refers to the etched circuit board, but should be helpful 
for any type construction. 

Metering to the placement guide ( Figure 3) note that all parts 
on the interface are inserted from the component side of the 
board. That is, the side WITHOUT the copper traces. Insert and 
carefully solder the three 1C sockets in place. If you examine the 
sockets, you will notice one end ha* a small notch. Be sure this 
notch is at the pin 1 end as indicated in Figure 3. 

Insert muI solder the resistor packs (RP1, Rl^, RP3, RP4) as 
indicated, again paying attention to the orientation of pin 1. Pin 
I is indicated by a stripe or dot on the part. Insert and solder CI, 
C2, and C3 as indicated, and clip the leads neatly. Note the 
polarity of C4 on Figure 3. The capacitor itself has one lead 
marked + on the side of the capacitor. Insure that this lead is 
inserted as indicated. Solder and clip the leads. 

Install nine jumpers as indicated using either your left over 
capacitor leads, or small lengths of wire. Solder and neatlv trim 
the jumpers. Next, insert and solder the 50-pin SCSI connector 



The 86-pin connector to the Amiga poses a bit of a problem. 
For simplicity of design, the board is constructed so that the 
connector slot i.s parallel to the board. Normally this requires an 
86 pin right angle connector. That is, the pins exiting from the 
back of the connector make a right angle turn. However these 
connectors are not available in small quantities. If you are lucky 
enough to locate one, simply solder it in place. Otherwise you can 
modify the connector listed on the parts list to do the job nicely. 
Refering to Figure 4, carefully bend one row of pins on the 
connecter at a right angle. Insert this bent row of pins into the row 
of holes CLOSEST to the edge of the board. You may wish to put 
a drop or two of super glue to fix the connector in place on the 
board. Once in place, solder the row of pins. Now, using short 
lenghts of wire, such as resistor leads, connect the remaining pins 
of the connector the the corresponding hole as shown in the 
drawing. Solder in place both at the pin, and on the circuit board. 

Install the dip switch as indicated. The dip switches are for 
setting the base address of your interface. Refering to Figure 5, 
you can see that each switch refers to a bit in the base address \ 
closed switch is a 0, and an open switch is a 1. Several example 
settings are shown, fust note that the high bit is the switch closest 
to the SCSI connector and the low bit is the switch closest to the 
Amiga connector. Set the switches to agree with your base ad- 
dress. 

Check your parts placement, and soldering. Insure that you 
have no solder "bridges". All it takes is one 'OOPS' and you could 
damage your interface or computer. Once you are done checking 
your work, have someone else double check it for you. If all 
checks OK, proceed with inserting the IC's. 

NOTE: IC's are STATIC SENSITIVE. Use proper measures 
to prevent damage. If you are unsure of how to do this, please 
have someone who is, insert your IC's for you. 




Figure One 

The Spartan PCB Layout 
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Figure Two The Spartan Schematic Layout 



ALL CAPACITANCES IN MICROFARADS 
C1-C3 CERAMIC DISK 
C4 TANTALUM 




SPARTAN 

SCSI INTERFACE 

<C)1991 PaulHarker 



Insert the three IC's in their respective sockets, insuring that 
pin one is correctly positioned. The pin one end can be identified 
by either a notch at the end, or a dot next to pin one. This pin one 
should be at the pin one end of the socket. This completes the 
assembly of your Spartan interface! 

Assembling the SCSI System 

In addition to (he Spartan interface and software you will 
require the following: 



SCSI Hard Dnve (or Adaptec 40X0/ST506-4 1 2 

combination) 
50-Pm SCSI Cable 
IBM PC/XT type power supply 
Power cable for power supply 
Enclosure for dnve and power supply 

An IBM 'clone' case will accept both the power supply and 
the hard drives nicely, and are available inexpensively from 
many sources. While powering a small hard drive directly off the 
power supply of the Amiga 1000 is possible, 1 don't recommend 
it and it is absolutely prohibited with the minimal power supply 
of the 500. 
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Figure Three 

PCB Component Placement 




Figure Four 

86 Pin Connector Modification 




Use Short Length of 
Wire and Solder at 
Both Ends. 



Bend At Right Angle 
ana Solder. 



Ensure that the Amiga is turned off and connect the as- 
sembled Spartan interface to the expansion bus. On the 500, 
simply remove the snap on cover from the left end. and firmly 
push the interface in place (components lacing up if using the 
etched board). On the 1 000, the interface installs on the right side 
of the computer (once again, component side up). 

At this time, take a deep breath, and power up your Amiga. 
If it does not boot up properly, IMMEDIATELY turn the power 
off and recheck all your work. If you continue to have problems, 
see the section on PROBLEMS. 

Turn off your Amiga. Install the 50 pin SCSI cable between 
the interface and your hard drive. Insure that pin 1 of the cable is 
at the pin 1 end of the connectors at both ends. Recheck all 
connections. Once you are sure your cabling is correct, proceed 
with formatting. 

Formatting 

Hard drives require two forms of formatting, the low-level 
(physical) format, and the high-level (logical) format. The high- 
level format is what you are already familiar with. That is, it is the 
type of format you perform when using the 'Format' command 
from AmigaDOS or 'Initialize' from the Workbench. The low- 
level format, which is only used on hard drives, marks bad sectors 
of the drive as unusable, sets the interleave (more on this later) 
and stores important information about the configuration. 

A set of low-level format utilities, AFormat, for Adaptec 
controller /ST506 drive combinations, and SFormat, for standard 
SCSI drives, are included on disk. These are executed from the 
CLI by typing 'AFormat' or 'SFormat' at the DOS prompt. You are 
then presented with a series of questions about your particular 
configuration. Once these are answered, it then performs a com- 
plete low-level format of your drive. These programs tie up the 
SCSI bus completely, so do not attempt any other SCSI access 
while performing a low-level format, or you will meet theGURU. 

To perform the low-level format, first boot your Amiga, and 
open a CLI. Turn on the power supply to the hard drive. The hard 
drive will go through some initialization activity. This mav be 
indicated by the flashing of the led on the drive and controller. 
Once this activity is finished, run the low-level format utility for 
your drive. You will be prompted for information regarding your 
particular configuration. AFormat requires much more informa- 
tion than does SFormat. You need to know several things about 
your hard drive to perform a low-level format. This information 
should have been included with the drive A text file on disk, 
'DriveSpecs', gives the needed information for many popular 
hard drives. If you can't find information for your drive, contact 
(he drive manufacturer. 

AFormat will prompt you for: 



Mount your drive and power supply in your enclosure, 
insuring that the circuitry does not short to the case or to another 
component. Layout is not important. Plug a power connector 
from your power supply into the power socket on the hard drive. 
Set the SCSI address of your drive to as directed by the owners 
manual. 



Base address 
Adaptec Card Type 
SCSI Address 
Onvet 

Number of Cylinders 
Number ot Heads 
Step rate 
Interleave 

Reduced Wnte Current 
Enter Cylinder f 



Base address in HEX 

Enter 1 lor the 4000(A), 2 tor the 4070 

Enter the drrves address 

Dnve connects to JO and Drive 1 connects 

to Ji (reler to the Adaptec Manual). 

Enter the number ot cyhnders 

Enter the number of heads 

Enter the step rate ot your dnve 

Enter 2 

Enter V or K 

Enter the starting cylinder number 

for Reduced Wnte Current. 
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AFormal will then prompt for information regarding me- 
dia errors on your hard drive. This information is normally noted 
on a label attached to the drive. Enter this information as re- 
quested. To terminate error entry, enter a (zero) at the 'Cylin- 
der:' prompt. 

SFormat is much simpler to use and only prompts for base 
address. SCSI address, and the interleave: 



Base address 
SCSI Address 

interleave 



Base address m HEX 
Enter the dnves address 
Enter 2 



Following data entry, you will be given a last chance to bail 
out. If you continue, the drive will become active for about 5 
minutes. (20MB drive, correspondingly longer on larger drives). 

If you have an non-standard SCSI hard drive which will not 
format with SFormat, it will work with your Spartan interface if 
it has been low-level formatted. The drive can be formatted on 
another computer as long as the bytes-per-block is 512. in fact 
most SCSI drives are sold with a 512 byte-per-block low level 
format already on them. The Macintosh and Amiga both use this 
block size, so you can format your drive (low-level) on another 
computer, then hook it up to your Amiga to perform the DOS 
format. 

For those with C language experience, the source code for 
SFormat is included on disk. This can be easily modified to 
conform to the low level format command sets used by non- 
standard SCSI drives. This source is compilable by Aztec C. 

Make a copy of your AmigaDOS 1.3 Workbench. This will 
bereferedtoasyourbootdisk.Thecopyofspartan.deviceondisk 
isaddressed to base address F7. If yourSpartan interface is at base 
address F7, simply copy spartan. device from the DEVICE direc- 
tory into the devs: directory of your boot disk. However, if you 
have a base address other than F7, you must use the supplied 
utilty. SetBase, to modify the base address of spartan. device. 

The usage of SetBase is: 

SetBase <fiiename> <BaseAddress> 



DHO: 

Device = spartan. device 
Unit = 
Flags = 
Surfaces = 4 

BlocksPerTracff = 17 
Reserved = 2 
LowCyl = ; 
HighCyl = 614 

Buffers = 30 

BulMemType = 

MaxTransfer* 131071 
Slacksize = 4000 
GtobVec = -1 

FileSystem = LFastFiieSystem 
DosType = 0x44415301 



;See Text. 

;not used 

;Numberof heads on 

;drrve 

;See Text 

;Don'l change 

; Bottom and top 

;cylinder numbers; 

; Refer lo AmigaDOS 

; manual 

:Refer to AmigaDOS 

;manual 

; Don't change 

; Don't change 

; Don't change 

; Don't change 

; Don't change 



A copy of this file is on disk. Some entries require explana- 
tion. Enter as the unit number for your first hard drive. Unit 
numbers for additional drives are discussed in the 'Multiple 
Drives' section of this article. For an intial setup enter for 
LowCyl and enter thenumber of cylinders, minus one. for HighCyl. 
The interleave in the mountlist is ignored bv Spartan, as your 
interleave has already been set by the low-level format. Enter the 
blocks-per-track of your SCSI drive (17 is usual), or if using an 
Adaptec controller enter 18 for the 4000(a) or 26 for the 4070. 

Once this is complete, edit the Startup-Sequence of your 
boot disk and add 'Mount DHO:' as the first command. Reboot 
your Amiga using your boot disk. From the CLI enter: 

Format dnve dhO: name MyDnveName quick 



Filename will normally be 'spartan. device' (including the path), 
and BaseAddress is the two character hex base address of your 
interface. SetBase will create a new file named '<fi!ename>.XX' 
where XX is the base address of the driver. Copy this new device 
to the DEVS; directory of your boot disk and rename it 
spartan.device. 

Edit your mountlist to include the following (modified to 
your configuration). Please note that unlike most AmigaDOS 
commands, the MOUNT command is t\isr sensitive. Be sure that 
the device file name and mountlist device entry match exactly. 



Figure Five 

SW1 Base Address Settings 



SW1 





Closed Switch - 
Open Switch ■ 1 

Kxample Base Addresses 

7 6 5 4 3 2 10 
1 1 I 1 I I 1 = F7 
00100000= 20 
1 1 I 1 I 1 = 6F 
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PARTS LIST 

PART DESC 


DIGI-KEY « 


U1 
U2 

U3 


74LS00 QUAD NAND GATE DM74LS00N 
74HC688 6 BIT COMPARATOR MM74HC688N 
(74LS688 acceptable) 
AM5380PC SCSI BUS CONTROLLER (See arttcle) 


Cl-3 

C4 


.047uW CERAMIC CAPACITOR 
22ufd TANTALUM CAPACITOR 


P4307(QTY 10) 
P4521 


RP1-3 
RP4 


6 PIN 220/330 Ohm TERMINATOR PACK Q1T04 
10 PIN IKohm PULL-UP PACK O9102 


SW1 


8 POSITION DIP SWITCH 


CT2088 


J1 

J2 


50 PIN SCSI CONNECTOR AHR50G-ND 
86 PIN EDGE CARD CONNECTOR C5-43 


18" SCSI CABLE 
36* SCSI CABLE 


A3AAT-5018GN0 
A3AAT-5036G-ND 


Wtf-Kty 

Broods Ave South 

P.O. Box 677 

Thief R(vef FaBs. MN 56701-0677 

1-800-344-4539 


Computer Surplus Store 
715 Sycamore Dr 
Miprtas. CA 95035 
(408)434-0931 
Adaptec contioSers 



You may omit the quick option. I low-ever, unlike a floppy 
there is no need lo write to each track. Your formatting will just 
take longer. You now have a fully useable hard drive which can 
be accessed like any other DOS drive! 

NOTE: The AmigaDOS version 1.3.2 Format command has a 
small problem with Spartan. After formatting with the 1.3.2 
Format command, you will get a 'Format Failed' message, and 
AmigaDOS will report 'Not a DOS Disk' if you try to access the 
dr)v«, Reboot, and AmigaDOS will recognize the disk as being a 
properly formatted DOS disk. The older 1 2 and 1 .3 versions of 
Format work without this problem. 

Optimijng Performance 

As you recall, when you performed your low-level format, 
you needed to enter the interleave. Interleave is the method that 
is used to store data on you hard drive in a manner best suited to 
your particular system. 

This discussion of interleave will focus mainly on reads, but 
the same information pertains to writes as well. Asa hard drive 
platter spins, the data is accessed one block (312 bytes) at a time, 
and then sent to the computer. As the platter advances to the next 
block, often the computer is not quite ready to receive more data, 
and the platter has to make a full revolution before the heads are 



again in position to read the block. However, this full revolution 
is much more time than the computer needed to be ready, and 
much time is wasted. This wasted time equates to low data tranfer 
speeds. What interleavedoes is alter the order in which blocks arc 
read and written. On a hard drive without interleave (referred to 
as an interleave of I), the data blocks are read/written sequen- 
tially: 

mi2ll3ll4|15llfill7l 

But with an interleave, they are 'shuffled' evenly, as shown 
in this example of an interleave of three: 

1*1091041 1S1 10 1051161 11106(171 

As you can see, block 01 is three blocks from block 02 (thus 
an interleave of three), so that the order of access is read one, skip 
two, read the next, skip two, etc. The time spent skipping blocks 
allows the computer to catch up and be ready for data when the 
drive is ready to send it. If the interleave is too large, the drive 
skips blocks while the computer waits, and if the interleave is too 
small, the drive is ready before the computer and must make an 
additional full revolution. 

What we want to do is select an interleave for the hard drive 
to get the best performance. The disk performance tester DPerf2 
will help in this task. The author was kind enough to allow this 
program to be included with Spartan. Please take the time out 
now to read his documentation (on disk). 

Run Dperf2 on your hard drive and write down the results. 
Re-format your drive (both low-level and DOS) with various 
interleaves to see what gives your system best performance. An 
interleave of 2 gives best performance with many drives. 

Be careful of one bug in DPerf2. If for some reason it is 
unable to access the specified drive, it writes all over DFO:, so be 
sure to write protect the disk in DFO:! 

Adaptec Users— 

To use an interim* of 1 , you must edit your mountlist to reflect 
one less BlocksPerTrack. For example a 4000(A) controller will noiv be 
BlocksPerTrack=17. and a 4070 will be Btock$PerTrack=25. You must 
reboot the Amiga, and 'MOUNT DH0:' for this to take effect. Togo back 
lo an interleave other than I, restore your mountlist BlocksPerTrack. 
and reboot. Note that you lose your extra 10% storage with an interleave 
of I. Refer lo the Adaptec Manual for details. 

All Drive Types— 

T)ie sequence for optimizing interleave: 



Aformat or SFortnat 
DOS Format 
Dperf2 



repeat... 



(Adaptec users: edit mountlist and reboot 
if going to/from an interleave of V 
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The Adaptec Controllers 



Adaptec produces a line of hard drive controllers which 
allow standard IBM type (ST50612) dnves to communicate as SCSI 
drives. Each controller supports up to two hard drives The 
combined cost of one ot these boards (as low as $80 from some 
suppliers) and a surplus or used IBM type dnve Is often an 
economical way ol adding drives lo Spartan. The Spartan software 
supports the following Adaptec controllers: 

4000 The original MFM model 
4000A The standard MFM model 
4070 Supports RLL drives 

The Adaptec 4070 is an RLL (Run Length Limited) 
controller. RLL is a meihod ol stnng 50% more data on a hard drive 
than traditional methods. For example, a 20meg drive formats to 
30meg using RLL. However, to make use of RLL encoding, an RLL 
certified drive must be used Non-RLL (MFM) hard drives can be 
controlled wiih the Adaptec 4000 or 4000A. 



One great feature of the Adaptec controllers is an unique 
method of stonng data. Due to this method of data storage, each dnve 
formats to 10% LARGER than normal. So a 20meg MFM dnve would 
format to 22meg. and a 20meg RLL drive would format to 33megf 

To use an Adaptec controller with Spartan you would require 
the following: 

Adaptec Controller with User's Manual 

(4000, 4000A or 4070) 
ST50612 type Hard Dnve 
34 Pm Card Edge Ribbon Cable 
20 Pm Card to Socket Ribbon Cable 

The user's manual does NOT come with the controller and 
has to be ordered. Refer to this manual tor any questions you have 
regarding interfacing your dnve to the Adaptec controller. 



Multiple Drive Configurations 

Spartan supports seven SCSI devia-s. UsingAdaptecdrives. 
this allows a system containing up to 14 hard drives! Although it 
is seriously doubtful that anyone would take it that tar, it is 
possible. The following section details the information needed to 
attach additional drives to the Spartan system. 

Adaptec controller users can add a second drive (drive 1 ) to 
the controller as described in the Adaptec manual. Be sure to 
address your second drive as drive 1, and remove the terminator 
resistor from drive 0. 

Adding additional SCSI drives is not difficult. You need a 
SCSI cable with additional connectors to daisy-chain as many 
drives as you are using. Remove the terminator resistors from all 
but the last drive on the SCSI cable. Also, be sure your power 
supply can handle the load of the extra drives. 

To communicate with drives, you need to set the SCSI 
address of the drive to an unused address between and 6. Refer 
to your drive manual for details on how lo configure vour drive's 
SCSI address. Address 7 is reserved by Spartan. Use this SCSI 
address when performing the low-level format on this drive. 

Each drive must have it's own mountlist entry to be used as 
an AmigaDOS drive. The unit number in the mountlist tells 
Spartan at what SCSI address to find the drive. The following 
chart demonstrates this. 



MountList Unit » Assignments 


Urnit 
SCSI DnveO 


Uniw 
Dnvel 


t 

1 2 3 

2 4 5 

3 6 7 

4 8 9 

5 10 11 

6 12 13 

7 Reserved lor Spartan 



Only Adaptec controllers with a second drive use the drive 
I unit numbers. All other SCSI drives use the Drive numbers. 

So, as an example, if you set the unit" in your mountlist to 
6, Spartan will interpret this as drive at SCSI address 3. 

Once a drive has been connected to the system, and a 
mountlist prepared, the drive must be low-level formatted, 
mounted and a DOS format performed. The drive will then be 
ready for use. 

Partitioning Your Drive 

Unlike floppy disks, hard drives can be partitioned. What 
this means, is that one large hard drivecan be made to act like two 
or more smaller ones. This isespecially useful on very large drives 
to prevent file fragmentation, and speed disk access. 
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To partition a drive, you must againedit the mountlisl. Each 
partition requires a separate mountlist entry. For example, you 
could partition a 20MB drive as one 10MB drive, and iwo 5MB 
drives. Lets call our 10MB partition DHO:, our first 5MB partition 
DH1: and our second 5MB partition DH2:. 

For the purpose of our example lets assume our 20MB drive 
has 600 cylinders. If we were to mount this as a 20MB drive we 
would have a mountlist entry with the following line: 

LoCyl=0. HiCyl=599 

To partition the drive we would first create mountlisl entries for 
all three partitions (DHO: DH1: and DH2:). The mountlist entry 
for DHO: we would edit the cylinders as: 

LoCyl=0. HiCyl=299 

This gives our DHO: access to the first half of the drive. For drive 
DH1: and DH2: we would edit the mountlist entries as follows: 

LoCyt=300, HiCyl=449 ;(DH1) 
LoCy1=450. HiCyl=599 ;(DH2) 

This gives both DHL and DH2: one quarter of our hard 
drive, or 5MB each. Be sure that your partitions cylinders don't 
overlap. A complete example mountlist is on the disk with the 
filename Partition. exam pie. Remember that each partition re- 
quires it's own mountlist entry and device name. 

The drive must be low-level formatted, however separate 
low-level formats are not needed or possible for partitions. Each 
partition must be be MOUNTed and separately formatted with 
the AmigaDOS formal command. 

Hooting your Hard Drive 

Although Spartan does not autoboot.itcan be easily used as 
.i 5) --tem disk by means of your boot disk. First, copy the entire 
- 1 intents of an original Amiga Workbench 1 .3 to your hard drive. 
Replace the sstartup-sequenceonyourboot disk with the startup- 
sequence from the Spartan archive. You may want to copy 
'disk.info', also, (I'm no artist, but I like it!). What this startup- 
sequence does is simply mount DHO:, ASSIGN all system dire. 
tories to DHO:, then EXECUTE the startup-sequence in S: (now 
assigned as DH0:S). 

To boot your system, power up your computer. Insert Kickstarl 
if you have a 1000. Turn on your hard drive, and wait for 
initialization activity to cease. Now insert vour boot disk, and 
everything else takescareof itself. Once thesystem is running, the 
boot disk is no longer needed. 

Notes 

Amiga 500 owners may wish to leave the boot disk in the 
internal drive at all times, and use a single switch to power both 
computer and hard drive. However, if the hard drive has not 
finished it's intializa lion when the startup-sequence starts access- 
ing it, the system will lock up. To a void this, insert an appropriate 
length WAIT command immediatelyafter the MOUNTcommand 
in your startup-sequence. 



The 5380 SCSI controller I.C. is manufactured by several 
vendors, including AMD, LOGIC Devices, and NCR. I have 
tested the AMD and the LOGIC Devices versions, and ol the two 

only the AMDde* ke is compatible with the Spartan software. 
Some ST506/41 2 drives have errors mapped on sections of 
thedrive that Adaptec controllers do not format [nflse errors Will 
cause AFormat to fail. Do not enter any errors mapped in a 
cylinder higher than your high cylinder, and any errors with a 
bytes-from -index higher than: 



Interleave of 1: 
Other Interleaves: 



4000(A) 4070 

9792 9817 

10188 10036 



The most likely causes of a newly constructed interface to 
not work, are solder bridges and bad solder joints. Clean your 
board's foil side withisopropyl alcohol to make it easier toseeanv 
problems. 

Check that your cables are all in good shape and are 
properly oriented. Inspect the pin one orientation of all IC's and 
r.-sistor packs (RP1, 2,3). Kan 1C was installed backwards, and the 
power applied, it was most likelv dest roved. 

Check that C4 is installed with the * as indicated in the 
drawing. If you put this in wrong, a small puff of smoke from it 
will probably let you know It this happens, it can be replaced 
witha tantalum capadtor with a value oM5 to 22 uFat 6 volts or 
more. 

Another likely problem is improper addressing of either the 
interface or of spartan. device, lie sure you have selected a valid 
base address for your system. Check that you have properly set 
the dip switches on on your interface and that you have set the 
base address ol spartan.device using Sol Base. 

There are two simple troubleshooting programs in the 
Low-Level directory, Aiest.andSTest. rheseprogramsare paired 
down versions ol AFormat and SFormat, which will not perform 
a format, just establish communication with the drive. 

Conclusion 

I sincerely hope that Spartan opens up your world of 
computing as nui. has it has forme. An Amiga wiiha hard drive 
is so much more powerful and versatile, that it's like using a 
completely new machine. 

rhe etched and drilled circuit board and the hard to find 
AM5380 are available from (he author. The prices are as follows: 

Etched and Drilled Circuit Board 520.00 
AM5380 SCSI Controller $15.00 

Add SI.50 shipping for each order. Write for quantih 
discounts on orders ol rh e or more. Send check or money order 
to: Harker Electronics, 255 Valley N.W., Grand Rapids, Ml 49504 

I am unable to answer questions about Spartan by phone, 
but can be contacted bv mail or via GFnie P. Harker, or 
CompuServe 71546,1665. 
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APPLICATION DESIGN— PART 3 

OBJECT-ORIENTED CAD 



BVFORHSTW ARNOl 



Introduction 

C* + . SmallTalk, Eifel, Flavors, objects, class,--. 
BOO PS1... OOPS! Nowadays, just about every software maga- 
zine you pick up has a reference to at least one of these program- 
ming languages or terms. It seems as though programmers .ill 
over the world have jumped on the band wagon of object-oriented 
programming and are busilv creating objects. Since we don't 
want to be left behind eating technological dust, we're also going 
to jump on board! We are going to develop an architecture for 
implementing geometric objects as true object-oriented objects. 
and de\ ,]op several "classes" ol objects lor our mini-CAD pro 
gram — and without an object-oriented language, just plain old 
\\s| t and Mum- programming ami software packaging tricks! 
But first, we need to take one more look at geometric transforms, 
and then see how to interactively create new graphical objects 
using the event-dm en programming met hods we developed last 

time {AC's Ttch, Vol 1.3). 

Geometric Transforms Revisited 

In Part 1 of this series, we discussed the geometric trans- 
forms Used to translate (move), rotate, and scale (resize) geomet- 
ric objects modeled with vectors, which are just point coordi- 
nates Translations are the simplest transforms: we simply add a 
vector (x,y coordinate pair) to all the coordinates defining a 
model object. Scaling and rotation transformations arc more 
complicated, since both of these transformations require "refer- 
ence points \\ hen an object is scaled, all the coordinates in the 
object either mine away Irom the reference point or move toward 
the point, and when an object is rotated, all its coordinates move 
in a circle around the reference point. To correctly rotate or scale 
an object, we first translate the object's coordinates so the\ are 
relative to the reference point, rotate or scale the object, then 
translate it hack to its original location. 

How do we choose a scale or rotation reference point? One 
was is to have the CAD user make the decision by picking a 
reference point Another way is to use the initial "pick point" as 
the reference point, and still another way is to use ^m arbitrary 
point. This is the technique we used in Part 2of this scries. Objects 
were rota ted and scaled using the centers of their bounding boxes 
as the transform reference points. We will again use an arbitrary 
reference point to transform the objects in our mini-CAD pro- 
gram. However, instead of always using the center of an object's 
bounding box, the reference point will depend on the transform 
being applied. For rotations, the reference pointwill be the center 
ol the object's bounding box; and for scaling transforms, the 
reference point will be the corner ol the bounding box which is 
diagonally opposite the corner closest to the pick point on the 
object. 



Another common transform provided in most CAD sys- 
tems is "flipping" objects. In this version of our mini-CAD 
program, we will add a "flip" menu item to our "Action" menu. 
Objects are flipped by interchanging their tops with their bot- 
toms, or by interchanging their right- and left-hand sides ,\s an 
example, suppose we have a triangle whose coordinates .ire: 






Figure l shows how this triangle will look after being 
flipped horizontally around the point (0^)) and vertically around 

the point (5,3). The transform to flip an object is just a scaling 
transform with negative scale values. Since objects are flipped 
with scaling transforms, a flip reference point is needed. In our 
mini-CADprogram.wewilluscthepickpointontheobjectasits 
flip reference point. The scale matrix to flip our example triangle 
horizontally around the point (0,0) is: 



-1.0 




0.0 


. 


0.0 


0.0 



And to flip it vertically around the point (5,3), the overall 
transform matrix is formed by the following sequence of matrix 
multiplications (in our program, we call our transform library 
matrix procedures to i\o this work): 



Translate to 
original location 



Scale 



Translate to flip 
reference point 





... 










1.0 




1 









- 



.- 



As Figure 1 shows, after an object is flipped, it will not be in 
its original location, unless it is flipped around its center. Some 
CAD systems automatically move flipped objects back to their 
original locations. 

New Program Commands 

A CAD program which can transform objects is not very 
useful unless it can also create objects, so we are going to add 
object creation procedures to our program. The new procedures 
will enable us to interactively add rectangular shapes, polylines, 
and polygons to our model world. We'll also add procedures to 
delete objects, to view and modify an object's values using a 
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Figure One Flipping Objects 
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Figure Two Linking Objects and Procedures 
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"Show/Edit" requester, to flip objects, and to move the indi- 
vidual points in a line or polygon. The following paragraphs 
describe the program commands associated with these proce- 
dures and the user actions for executing them. 

Objects are added lo a drawing window by first picking an 
"Insert" menu item, followed by a menu subitem for the type of 
object to insert. The menu item-subitem choices are "Insert- 
Shape," "Insert- Line,'' and "Insert-Polygon." Shapes are rect- 
angles, lines are a series of two or more points connected by line 
segments, and polygons are lines whose first and last points 
coincide. Thus, polygons are just closed figures constructed with 
points and line segments. After the "Insert" menu pick is com- 
plete, the object is added by picking its starting coordinates, 
dragging the cursor to locate another set of coordinates, and then 
"clicking" the select button. For shapes, the two sets of coordi- 
nates define two of the rectangle's corners, and the shape insert 
action is complete. For lines and polygons, the coordinates define 
the first line segment. To continue adding points to lines and 
polygons, one drags to another location and presses the select 



button to add the new point. The line and polygon insert action 
is completed by "double-clicking" theselect button at the location 
desired for the last point. If the object being inserted is a polygon, 
the program will automatically add a line segment to connect the 
first point to the last point. 

Objects are deleted by picking a "Delete" menu item, and 
then picking the object to delete. The picked object is deleted and 
erased as soon as it is selected. "Flipping" objects is performed in 
the same way. The "Flip" menu item and one of its subitems is 
selected, then the object to be flipped is picked. There are two 
"Flip" menu subitems: "Horizontal" and "Vertical." As soon as 
the object to be flipped is picked, it is erased, flipped around the 
pick point, and redisplayed. 

The individual points in a line or polygon are moved bv 
selecting the "Move" menu item, then selecting a point and 
dragging it to a new location. The command to move points is an 
implicit command: either the entire lineor polygon, or just oneof 
its points will be moved, based on what part of the object is 
selected. If the cursor is close to a point (within three pixels) when 
the select button is pressed, only the point is moved. Otherwise, 
the entire object is moved. 

An object's location and size valuescan be viewed or edited 
by picking the "Show/Edit" menu item, then picking the object. 
A "Show/Edit" requester pops up in the drawing window when 
the object is picked. The requester contains labels and string 
gadgets which show the object's current position (minx.minv) 
and size ( width,height>. The selected object's values are changed 
by typing the new values into the labeled string gadgets. Chang- 
ing the x and y values will move the object to a new position, and 
changing the width or height values will resize the object. Objects 
can be flipped by entering negative width or height values. The 
requester alsocontains"Modify"and "Cancel" pushbuttons. The 
requester is popped down by picking either of these pushbuttons. 
If the "Modify" pushbutton is picked, the selected object's values 
are updated and it is redisplayed. Otherwise, the object is just 
unhigh lighted. 

Each of these new program actions is implemented with 
event handler procedures and event chaining. Let's briefly re- 
view how event handlers and event-specific data are attached to 
Intuition 's input objects (menus, gadgets,etc) and used to process 
input events. Recall that a pointer to an event handler procedure 
and a pointer to the data needed by the handler is placed into a 
structure typedef'ed "intuiExtensionj". A pointer to this struc- 
ture is then attached toan Intuition input object. If the input object 
is a gadget or window, the intuiExtensionj structure pointer is 
placed in the "UserData" member of the gadget or window 
structure. Since Menultem structures do not have a UserData 
member where we can place our intuiExtensionj structure 
pointer, we define our own menu item structure which includes 
both Intuition's Menultem structureand our extension structure. 

Theextended menu item structure is typedef'ed "myMenuItem J." 
When an input event is received in "handlelnputf )," the 
intuiExtensionj structure pointer is retrieved from the input 
object, and the event handler is called using the function pointer. 
The event handlers either directly perform an action, such as 
closing a window, or place information in the program's state 
vector for use by another event handler. The state vector in our 
program is a structure called "world." 
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Let's look at Ihe new program commands, the event han- 
dlers for each, and the data sent to the handlers. We'll then see 
how the handlers and data are used to implement the new- 
commands. Table 1 lists the commands, the handlers responsible 
for the commands, and the data sent to the handlers. 



Table One New Program Commands 



Command Event 



EverrtHandter Handter Data 



Insert-Shape 


MENUPICK 


miSetAction 


msShapeData 


Insert-Une 


MENUPICK 


mSetAction 


insLineData 


Insert-Polygon 
Delete 


MENUPICK 
MENUPICK 


mSe (Action 

miSelAction 
mi Se (Action 


insPolyOata 
deleteOata 


Flip-Honzontal 


MENUPICK 


HipXData 


Flip-Vertical 


MENUPICK 


miSetAction 


IlipVData 


Show/EoM 


MENUPICK 


miSetAction 


showEditOata 


Modify 


GAOGETUP 


updateVaJues 
canceiRequester 


seRequester 


Cancel 


GADGETUP 


seRequester 



The last two commands in Table 1 are the "Show/Edit" 
requester commands which update an object after its values .in- 
modified, or cancel an edit action. The interlace objects for these 
two commands are pushbuttons in the "Show/Edit" requester. 
The data sent to the event handlers for both of these commands 
are pointers to the requester containing the pushbuttons. The rest 
of the commands in Table 1 are menu commands. The data sent 
to miSelAction( ) for each of the commands are instances of a 
structure typedef'ed "miData_t." This structure contains a func- 
tion pointer to an "action" function, an action modifier, and a 
pointer to whatever data the action function needs to do its job, 
Table 2 shows the miDataJ structure members for each ot the 
new menu commands. 



Table Two 

Structure Name 


New Menu Command Handler Data Elements [ 
Action Procedure Modifier Action Data 


insShapeDala 
insLineData 


dragAndinsert 
dragAndinsert 


N : M 
None 


shapeClass 
HneOass 

pdyClass 
None 


insPolyOata 


dragAndinsert 


None 
None 


deleteOata 


pickAndDelete 


showEditOala 


picKAndEdit 


None 


None 


IlipXDaia 


pickAndFbp 


FUPX 


None 
None 


tlipYData 


pickAndFl*) 


FLIPY 



The action data for the first three structures are pointers to 
other structures. We will discuss these three structures in more 
detail below. They are used in "dragAndlnsert( )" tocreate shape, 
line, or polygon objects. The modifiers stored with the flip data 
are used in "pickAndFlipf )" to determine which direction to flip 
an object. 

Program File Qrganiytiion 

Since our mini-CAD program now has quite .< bit of code, 
the source code has been split up and placed in several files, and 
the data structures and procedures in Table's 1 and 2are no longer 
in a single file. The following is a complete list of all Ihe program 
files and brief descriptions of their contents 



Program source code and include files 



globalDefs h global structure definitions and declarations 

•eHandiers.h declaration of the event handlers and action procedures 

defined m tstObjectc 
tstOOjectc mam program, event handlers, action procedures, and intu- 

itwn-reiated procedures 
menu c menu definitions and menu procedures 

menu h declaration of menu array, menu action modifiers, and menu 

procedure declarations 



handlelnput c 
handlelnputh 


delmes handlelnput( ) and handleDragf. ) 
declarations tor handielnputj ) and handleDragf ) 


Transform source code and include files 


transform c 
transform, h 


2d transform and matnx procedures 

declarations and macros lor transform and matrix procedures 




Shape object source code and include files | 


shape e 


shape class and object interlace procedures 


snape.h 


declarations for shape class interlace procedures 


shapeClass c 
shapeOassP h 
shapeClass h 
shapeUtilx 


implementation He for shape class and shape objects 
private include fite to* shape class, 
public include file tor shape class 
geometric utility procedure definitions shape 


Ul.lh 


declarations for geometric procedures. 


Line object source code and include files 


linec 
bne.h 


line class and object interface procedures 
declarations (or hne class interface procedures. 


iineCiassc 


line class and line object implementation file 


kneOassPh 
iineClass.h 


private include Me (or line class, 
public include file for line class 


Polygon object source code and include files 


poh/Ciassc 
potyOassP.h 


polygon class and object implementation die 
private include We (or polygon class. 


polyClassh 


public include file for polygon class 


Make/Link files 


tstObjecl make 
Object mk 


makefile lor comprtng the executable program, tstObject.tsl 
fcnk file (or Imkmg object modules 



Implementing ihe Sew Program Commands 

Now thai we know what the event handlers for our new 
commands are, know when' thev are located, and know how to 
interactively use the commands, let's look at how the commands 
are implemented. All Intuition eventsare received in handlelnput! 
). When an even) is received, hand!elnput( ) retrieves the pointer 
to the intuiE*tension_t structure stored in the input object's 
Structure. The function whose pointer is in the intuiExtension_t 
structure is then called. For all our new menu commands, 
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miSetAction( ) is the procedure called by handlelnpull ). 
MiSelAction( ) is simple: it places the data sent to it into the 
program state vector (named "world") and returns. MiSet Action! 
Jsets the "action", "modifier",and "data" membersof the "world" 
structure equal to the corresponding values in the miData t 
structure pointer sent to it. If the next event received by 
handlclnpul* ) is a MOUSEBUTTONS event, windowEvent( ) is 
called to take care of it. For select button events. Window Event* 
) calculates the world coordinates corresponding to the window 
coordinates where the button was pressed. It then stores both the 
world and window coordinates in the state vector. Finally, if the 
action member of the state vector contains a valid action proce- 
dure pointer, the action procedure is called. Our new action 
proceduresaredragAndlnsert(),pickAndDeleteO,pickAndEdit( 
), and pickAndFlip* ) 

Drag And Insert* ) is responsible for creating new objects. It 
retrieves the "class" structure pointer from the state vector and 
calls createShapef ), which creates new objects by allocating and 
initializing memory' for them. After an object iscreated, insert Drag) 
) is called. InsertDragf ) takes care of the drag interaction for 
establishing initial locations and sizes for new objects. The new 
objects are then added to the list of world objects and displayed. 
InsertShapc* > adds objects to the list of world objects, and 
displayShapct ) draws them. 

The action procedure for deleting i >hje* NispukAndDcIetel 
). It calls findObjectf ) to see if an object is located at the 
coordinates where the select button was pressed. If an object is 
found, it is erased, removed from the list of world objects, and 
deleted. EraseShapef ) erases any object, removeShapef ) takes 
care of removing them from the list of objects, and deleteShapei 
I frees memory allocated for objects. 

The action procedure which pops up the "Show/Edit" 
requester is pickAndEdil* ). This procedure determines which 
object was picked, highlights it, and then queries the object to 
determine its current location and size values. The position and 
size values are placed in the requester's string gadgets, and the 
requester is popped up. The pointer to the picked object is saved 
in the state vector so the action procedures which pop down the 
requester can tell which object was selected. This is all that 
pickAndEdit( ) needs to do, so it returns. While the requester > s 
displayed, the values shown in the requester's string gadgets can 
be edited. The "Show/Edit" requester is popped down when its 
"Modify" or "Cancel" pushbutton is picked. When the "Modify" 
pushbutton is selected, its action procedure, updateValues* ), is 
called by handlelnputf ). This action procedure reads the edited 
values from the requester's string gadgets, pops down the re- 
quester, erases the selected object, and updates it with the new 
values. Cancel Requester! ) is the action procedure called when 
the requester's "Cancel" pushbutton is selected. All it does is pop 
down the requester and unhighlight the selected object. 

An object's data values are obtained by calling 
getShapeValues( >, and they are updated by calling 
setShapeValues( >. GetShapeValues* ) iscalled from pickAndEdit* 
), and setShapeValuesf, ) is called from updateValues( ). Each of 
these procedures is sent an array of name-value pairs. "Name" is 
a data element identifier, and "value" is a pointer to a variable 
containing a value. GetShape Values* > returns the object's value 
corresponding to "name" in the value pointer. SetShape Values* 
) places the pointed-to value into the object's data element iden- 
tified by "name." Querying and updating objects without know* 
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ing anything about them is a tnckv problem. We'll take a look at 
the technique used by getShapeValuesOandselShapeValues*) to 
solve this problem a little later. 

PickAndFlip* ) flips objects horizontally or vertically IttirM 
finds the picked object, then examines the act ion modifier (FL1PX 
or FUI'Y) stored in the state vector to determine which wav to flip 
the Object If the object is being flipped horizontally, the (x,y) scale- 
values are set to -1.0 and 1.0, and if it is being flipped vertically. 
the *x,y) scale values are set to 1.0 and -1.0. PickAndFlip* ) then 
erases the object and calls resi/eShape* ), sending it the "flip" 
reference point (pick point) coordinates and the flip scale values, 
R« M/eShape( ) takes care of scaling objects. After resizeShapc* ) 
returns, the selected object is redisplayed, and pickAndFlip( ) is 
done. 

Moving the individual points in a line or polygon is a 
common CAD operation. Points are moved the same way entire 
objects arc moved: the point to be moved is selected, then 
dragged to a new location. DragAndMove( ), the move action 
procedure we developed last time, has been enhanced to move 
points belonging to a line or polygon. After dragAndMove* ) 
finds a selected object, it calls tmdPoint* ). It the --elected object 
does not contain points which can be moved (shapes), find Point* 
) returns a NULL pointer 1 lowever. if the selected object is a line 
or polygon, the pick coordinates are used to determine if the pick 
point is within a tolerance distance *3 pixels) of one of the line's 
or polygon's points. If so, a pointer to the point is returned. If 
findPoint* ) returns a non-NULL pointer, drag And Mo vei. Kails 
dragPoinK ) and movePoint* ) to move the point. Otherwise. 
movcDrag* ) and moveShapef ) are called to move the selected 
object 

Take another look at dragAndlnsert* >. It creates shapes, 
lines, and polygons without knowing what kinds of objects it is 
creating! It you look at the rest of the event handlers and action 
procedures in our program, you will see that none of them know 
what kinds of objects they are managing! DragAndlnsert* ), the 
event handlers, and the action procedures in our program illus- 
trate two important features of object-oriented programming: 
data hiding and polymorphism. The only information our pro- 
gram knows about the objects in it is how tocall their procedures. 
It does not even know the actual types of the objects. To our 
application code, all objects are of type "object_p", which is an 
anonymous type used to hide an object's real type. Notice also 
that all objects, whether they are shapes, lines, or polygons, are 
displayed by calling displayShapct >. Internally, displayShapct ) 
uses a function pointer to call the correct object drawing proce- 
dures without knowing what procedure it is calling. If the object 
is a shape, the code to draw shapes iscalled, and if it is a polygon, 
the polygondrawing procedure iscalled. "Polymorphism" (many 
forms) is the term used to describe this feature of object-oriented 
programming. In the remainder ol this article, we will take a 
closer look at the concepts and characteristics of object-oriented 
programming, and develop an object-oriented "framework" for 
implementing geometric objects. Let's get started with "objects" 
and "classes." 

Objects, Classes and Abstract Data Types 

The "object" and "class" concepts in object-oriented pro- 
gramming have the same meaning as they do in everyday lan- 
guage Things (objects) which are similar are grouped into cat- 



egories called classes. Similar classes, in turn, are grouped into 
categories of superclasses and subclasses. Mammals, for ex- 
ample, area subclass of a class of living creatures called animals. 

Canines are a subclass of mammals. Subclass objects are similar 
to their superclass objects, but are also different in some recogniz- 
able way. Software objects are grouped into software classes the 
.same way thai real objects are grouped into classes: all software 
objects which share the same data definition and the same Func- 
tionality belong to the same software class. I he individual soft- 
ware objects which belong to a dass are called "instances ol the 
class." or "class instant 

Soil ware classes are more than just conceptual groupings ol 
similar obje< ire programmer-defined data t\ pes Ihe\ 

consist of definitions of their instance objects' data structures, 
code implementing their objects' behavior, and a mechanism for 
linking instance objects to theircode. In C++, the "class" construct 
is a feature ot the language. It provides support tor programmer- 
defined data types, which are managed automatically in almost 
the same way built-in data types such as Integers and doubles are 
managed. Since we are not using C++, we have to create our 
classes and manage them ourselves. The basic programming 
construct for creating programmer-define.! data types in C ts 
"data abstraction." 

An abstract data tvpe consists of a data definition, the code 
for managing and manipulating the type (data definition), and a 
description of how to use the type. The transform structure and 
code we created in Part 1 is an example ot an abstract data type. 
Wecreated a data structure, typedef'ed it as "iransform2_t,"and 
wrote all the code needed for using transfbrm2_t structures. We 
created a programmer-defined data t\ pfi, I i |s '' t'ansform2_t's, 
we do not need to know anything about their internal data 
structure or how their code works. All we need to know is which 
procedures we can use with them, and how local! the procedures 
We implement and paek.ige any abstract data type the same way 
we did our transform2_t data type: all the code for the data type 
is placed into a single source code (xxx.c) file, and the structure 
and procedure declarations programs need to use the data type 
are placed in an include (xxx.h) file. This is the way we packaged 
our transform data type. The structure definitions and code for 
object-oriented objects are packaged in a similar way. Classes 
consist ot the "package" of code, structure definitions, and struc- 
ture declarations lor a single type ol object A class is the imple- 
mentation of .tn abstract Jala type, and objects which belong to 
the class are "variables™ of the data type 

Data Hiding 

The only problem with abstract data types is that the 
implementation details (data structures and code) for the types 
are usually visible to programs using them. Since the implemen- 
tation details .ire visible, the data elements for abstract data types 
can be directly accessed and modified. This is .1 temptation most 
programmers easily succumb to, usually under the banner of 
"efficiency." To remove this temptation, the data structures and 
code for object-oriented objects are hidden from applications 
which use them. 

To hide class implementation details, the prgram places the 

structure and procedure declarations for a class's objects into two 
include files. One include file is "public" and contains declara- 
tions needed by applications. The other include file is 'private' 



and contains declarations needed by theclass. As an example, the 
three tiles containing the implementation of shapeClass are 
shapeClass.c, the source code file, shapeClassP.h, the private 
include file, and shapeClass. h. the public include file. For our 
object-oriented implementation, brand new classes need two 
additional files ( me is a source code file containing application- 
class "interface" code, and the other is an include file for pro- 
grams using the interface code. Shape.c and shape.h arc the two 
interface files for shapeClass. All the include files for our three 
object classes (shapeClass, UneClass, and polyClass) arc in List- 
ings 1 through 8. 

In our mini-CAD program, all objects are visible only as an 
opaque pointer type, "object_p" (actually a "void *"). The real 
Structure definitions are contained in the private include files. 
the private files are included in our program (cheating!), 
we cannot access or modify the data elements for our objects. 
lurlher.all the internal procedures for each of ourobjecttypesare 
declared "static". Since static procedures are not visible outside 
their file, we can not directly call the procedures which imple- 
ment the functionality for our objects. This brings up a question: 
If both the data and the code for objects are hidden, how can the 
objects even be used? 

Binding Data to Code with Pointers 

1 mentioned above that classes contain a mechanism for 
linking the data for their objects to theircode. This mechanism is 
a structure containing function pointers which point to the code 
for the class's objects. The structure containing the function 
pointers is called a "class structure." It is declared in the private 
includefileforaclassand initialized in the class's source code file. 
A pointer to theclass structure is made available to code using the 
class's objects as an opaque type in the class's public include file. 
I he opaque class structure pointers in our program are named 
•*," " I meClass," and "polyClass." Their opaque type is 
"class p 1 he class structure pointers are used by our program 
when it calls createShape( ) to create objects. 

The Mrs! structure member of our object structure is a 
pointer to its class structure. The class structure pointer member 
ol an object is initialized when the object is created. By including 
the class structure pointer as part of an object's data, objects are 
indirectly linked to their code. Figure 2 shows how object struc- 
tures, class structures, and object procedures are all linked to- 
gether with structure and function pointers. Since the data struc- 
ture for an object contains a pointer to its class structure, which in 
turn contains pointers to the class's procedures, an object's proce- 
dures ,, in be indirectly called using its data structure. Here is a 
code fragment showing how the "display" procedure for shape 
objects is called: 

• .ip« object struct poire. 
data, '• shape class struct pointi 



::;ect->class; 

.play) lob iw) ; /• 






Because an object's procedures (operations) can be called 
through tin' class pointer which is part of the object, object- 
oriented Objects are "active" data, and are sometimes referred to 
as "actors 
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It isapparent from the abovecode fragment thai tocorreelly 
manage all the structure and (unction pointers associated with 
ob|i . N. knowledge of at least part of the implementation details 
of objects and classes is needed somewhere this knowledge 
consists of several pieces of information. Some code needs to 
know that object structures contain class pointers and that class 
structures contain function pointers. In addition, knowledge of 
which function pointers are contained in a particular class struc- 
ture, and what their linkage \ ariables are, is also needed. We do 
not want this kind of knowledge embedded in our CAD applica- 
tion code, since it would have to perform type checking and type 
casting to correctly use our objects. In fact, as mentioned above, 
this kind of knowledge is not even available to our application 

code 

When a new class is created, "interface" code for using the 
class and its objects is also created. The interface code is a set of 
procedures which provide access to a class's objects and their 
functionality. The interface code for a class is referred to as its 
"message interface" by object-oriented programmers, and calling 
one of the interface procedures is referred to as "sending a 
message"toanobjeet Most, lav. interface procedures do no more 
than the code fragment shown above: they just retrieve the class 
structure pointer from an object, then retrieve a function pointer 
from the class structure pointer and call the procedure. 

The interface procedures for our objects are in the files 
shape.c and line.c. Shape.c contains interface procedures for 
using any shape object, and line.c contains procedures for using 
line and polygon objects. The code in shape.c knows that shape 
objects contain pointers to a shapeCIass structure, knows which 
function pointersare in the shapeCIass structure,and knows how 
to call the shape object procedures through the function pointers. 
The code in line.c contains the same informal ion about line object 
structures and the lineClass structure. The procedures in shape.c 
and line.c are the ones called by the "action" procedures which 
implement all of our CAD functionality. 

The interface procedures for a class do more than simply 
provide access to the class's objects. One important function (hey 
perform is shielding application-specific program code from 
changes in data structures and code. The way classes and objects 
are defined and implemented can be changed without affecting 
the way they are used and accessed in application programs, as 
long as the way the interface procedures are called does not 
change. In addition, when combined with structure overloading, 
the interface procedures provide an important feature of object- 
oriented programming known as "polymorphism." 

Structure Overloading. Subclasses, and Polymorphism 

If we analyze all the different types of operations needed in 
CAD programs, we see that most CADoperations are common to 
all objects, whether they are circles, lines text strings, or Others, 
All CAD objects need display, erase, highlight, rotate, and scale 
operations, among others. However, some object types also need 
to perform operations which are not performed by other objects. 
Lines and polygons need operations for manipulating their indi- 
vidual points, such as an operation for moving the points. Circles 
and text objects do not need these operations In addition to a 
common set of operations, graphical objects also have a consider- 
able number of common data elements In our mini-CAD pr»»- 
gram, the data structures for all our objects contain pointers to 



their class structures, linked list "next" pointers, and bounding 
box coordinates. If we group the members of our structures so 
that those members which are common to different objectsare in 
the same positions in their structures, we can use "structure 
Overloading'' with our classes and objects. Structure overloading 
is a technique for defining new structures by adding structure 
members to the end of existing structures. The technique allows 
code written for existing structures to be used for the new 
structures. This technique is extensively used in object-oriented 
programming, and is also widely used in the Amiga system 
software (message and library structures, for example). 

I or our graphical objects and classes, the data elements 
common to all graphical objects are placed in the structure for 
shape objects, .im\ the function pointers for functions common to 
all graphical objects are placed in the. :lass structure for shapeCIass. 
1 hese structures are defined in shapeClassP.h (Listing 1). Notice 
that macrosare used to define the structure members. Macrosare 
used because they reduce the effort required to overload the 
Structures and change structure definitions. Now take a look at 
the class and object structure definitions for lineClass and 
lineObject in lineClassP.h (Listing 2). The structure definition for 
lineClass is almost identical to the structure definition for 
shapeCIass I he only difference is that lineClass extends (over- 
loads) shapeCIass, adding three new function pointers. Similarly, 
thestriu lure definition for lineObject extends sha peObject's struc- 
ture by adding a "points" pointer to shapeObject. Finally, take a 
look at the structure definitions for polyClass and poly Object in 
polyClassP.h (Listing 3). Other than containing empty macro 
definitions .is placeholders, these structures are identical to the 
lineClass and lineObject structures. These are all examples of 
overloaded structures. Let's line up our structure definitions side 
by side and compare their members. Table 3 compares our class 
structures and Table 4 compares our object structures. 



Table Three Class Structure Members 



shapeCIass, t 



meCiass t 



CLASS^PART CLASS PART 
SHAPEC_PART SHAPEC^PART 
LINEC.PART 



polyClass J 

CLASS.PART 

SHAPEC.PART 

LINEC.PART 

POLYCPART 



Table Four Object Structure Members 



shapeObjecM 

OBJECT_PART 
SHAPE.PART 



lineObjecLt 

OBJECT, PART 
SHAPE.PART 
LINE PART 



poryObject_t 

OBJECT_PART 
SHAPE.PART 
LINE PART 
POLY_PART 



Structure overloading can significantly reduce code vol- 
ume and eliminate code duplication. We can see why this is true 
from our class and object definitions. Since the definitions of 
lineClass and polyClass include the definition of shapeCIass, all 
thecode which i "knows" about shapeCIass can be used to manage 
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and manipulate the shapeClass part of the lineClass and polyClass 
structures. In thesame way, thecode which knowsabou t lineClass 
can be used for the lineClass part of the polyClass structure. These 
statements are also true for our overloaded object structures. In 
our mini-CAD program, shape .c contains the code which is used 
for all our overloaded class and object structures, and line.c 
contains the code for the overloaded lineand polygon classes and 
objects. As far as the procedures in shape.c are concerned, all class 
structures are shapeClass_t's and all object structures arc 
shapeObjecM's. The procedures in line.c view all the class and 
object structures sent to them as lineClass_t's and HneObject_t's. 
Let's return to our "display" example and see what hap- 
pens when objectsaredisplayed using function pointers from our 
overloaded structures. Suppose we have created and added a 
shape object and a line object to our model world, and are ready 
to redisplay all (bothl)of our objects. Todo this, we call "draw All( 
)", our application procedure which redraws all our objects. Here 
is the code from draw AII( ) which redisplays the objects: 

obj * world. objects; 

whilst obj I 
t 

I voidldisplay Shape (obj, window) ; 
obj ■ nextShape(obj) ; 



DisplayShapef > and nextShape( ) are defined in shape.c, 
and here are Iheir definitions: 



int displayShapef object_p object.window_p window | 
1 

class_p class * getc;- < ■ ' < -.(object); 

shapeClaSB_p shapeC = getShapeClasslclass) ; 



object's drawing procedure. For shape objects, the procedure 
which draws shapes as rectangles is called, and for line objects, 
the procedure which draws polylines and polygons is called. 

NextShapef ) works in a similar manner. It casts whatever 
object pointer is sent to it to a shapeObject pointer, and simplv 
returns the 'next' structure member stored in ever)' shapeObject 
structure. Since lineObject and polyObject structures overload 
shapeObject structures, nextShape( ) can access these structures 
in exactly the same way it accesses shapeObject structures. 

As tin--!' iwu examples show, the pTOCCdurea which ,ir. 
used for shape objects can also be used for line objects and poly 
objects, since the first part of their structure definitions are 
identical to the structure definition for shape objects. This means 
that either line objects or poly objects can be used wherever shape 
objects can be used. However, the opposite is not true; that is, 
shape objects can not be used wherever line objects are used, nor 
can line objects be used wherever poly objects are used. Imagine 
what would happen if the procedures in line.c cast the shapeclass 
structure pointer to a line class structure pointer and tried to call 
one of the procedures line class adds to shape class! Most likely, 
the software gremlin which lives in all code would probablv 
wake up and go to work! The generic interface procedures 
written for an extended object structure prevent this from hap- 
pening by looking at an object's class structure to determine 
whether it contains the necessary extensions before attempting to 
access them. This is similar to type checking. The procedure 
isClasslnstancef ) in shape.c compares an object's class structure 
pointer with an input structure pointer to see if they match. Here 
isa code fragment showing how the generic procedure findPoint( 
Jin line.c calls isClasslnstancef ) to verify the object sent to it is a 
line object or an object which extends line objects before it calls the 
findl'omt procedure line class adds to the shape class structure 
definition: 



it { I object n ! shapeC n : shapeC->display 

return 1; 
return r lshapeC->displayl 1 t object. window! ; 



• make sure the object is either a lineObject or 
■ an object which is an instance of one o: 

* class's subclasses. 



object_p nextShapef object_p object i 
i 

sh*peObject_p shape = tshapeObject_p)object; 

if I : object ) 
return NULL; 
return lobject_p) shape->next ; 

1 

The first thing displayShape( ) does is retrieve the class 
pointer from whatever object is sent to it (getObjectClass and 
getShapeClass are macros defined in shapeClassP.h to retrieve 
and cast class pointers). If the object is a shape object, the class 
pointer points to shapeClass. If it is a line object, the class pointer 
points to lineClass, but displayShape( ) does not know this. Since 
the lineClass structure overloads the shapeClass structure, it can 
be safely cast to the type. "shapeClass_p", and its memberscan be 
accessed and used as if it really were a shapeClass_p structure 
pointer. After making sure none of the pointers are NULL, 
displayShape( ) uses the display function pointer to call the 



if i : isciassiM- 
return NULL: 



ect. lineClass) | 



if I llneC->f indPoint > 

return (•( lineC-»f indPoint I t (object. px.py.ep3) ; 

And here is the definition of isClassInstancc( ): 

int isClasslnstancef objcct_p object ,class_p class ) 
I 

class_p objClass * getObjcctClasslobject) ; 

shapeClass_p shapeC ■ getShapeCla'ss (objClass) 

while ( shapeC I 
I 

class_p)shapeC >■ class I 
retur 
shapeC = getShapeClasslshapeC- 'superclass) ; 

return 0; 
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As we will six- shortly, each class structure contains .1 
pointer to the structure it overloads. The pointer is the structure 
member named "superclass" isClasslnstancel ) first retrieves 
the class structure pointer from the input object. Inside the 
"while" loop, the retrieved pointer is compared with the input 
dasa pointer, .ind if they match. isC I ass Instance) ) returns 1 to 
indicate the class pointers match. Otherwise, the pointers to the 
overloaded class structures are retrieved trom each class struc- 
ture and compared with the input class pointer. The loop contin- 
ues until the root class structure (shapeClass) has been reached 
and compared. When the code in line.c calls isClass!nstance( ) 
and sends it a line-Object, thecomparison succeeds immediately. 
If the object is a polyObject, the first comparison fails, since 
polyClass does not match lineClass. The second comparison 
Succeeds, since the superclass pointer retrieved from the polv 
class structure points to the line class structure. However, if the 
object is a shape object, the comparison will fail, since the shape- 
class structure does not overload the line class structure. 

When our application code calls the interface procedures in 
shapex and line.c, it does not know what kind of object it is 
sending to the procedures, and tin* called procedures do not 
know the "real" type of object sent to them. Nevertheless, the 
correct procedures for our different classes of objects are called. 
In object-oriented terminology, this typeol functionality is called 
polymorphism, and it is one of object-oriented programming's 
more powerful features. Polymorphism allows us to remove type 
checking from our code — no more massive switch statements to 
decide which procedures to call, and no more special casecode for 
different objects— we just call a procedure and the "right actions" 
are performed! What is almost magical about polymorphism is 
that we can add brand new objects and classes — created by 
overloading the shape class and shape object structures— to our 
program, and our existing code will automatically work without 
any changes or additions! Think about the significance of these 
statements 

From a conceptual viewpoint, lineClass and lineObject are 
spedalizedversK)!isotshapeC"lassandshapeObject*ndpolyClass 
and polyObuvt are specialized versions of lineClass and lineObject. 
Our overloaded structures form a hierarchy of class structures, 
together with their instance objects' structures. ShapeClass is a 
"superclass" for both lineClass and polyClass. and lineClass is a 
superclass for polyClass. Another way to describe the same 
hierarchical class relationships is by saying polyClass is a "sub- 
i lass of both lineClass and shapeClass, and lineClass is a sub- 
class of shapeClass. Subclasses specialize existing classes by 
adding new data or functionality, by modifying existing func- 
tionality, or both. With a few pointers and a couple of program- 
ming techniques, we can use structure overloading to implement 
"true" subclasses and "method inheritance," another powerful 
feature of object-oriented programming. 



remove this restriction. Method inheritance enables subclasses to 
use procedures defined by their superclasses without knowing 
the name of the procedures or where they are defined. 

You may have noticed in our CAD program that all objects 
are moved, resized, and rotated in exactly the same way. There is 
a good reason for this: all our classes use the same drag proce- 
dures for nun -nig. sizing, and rotating objects. The procedures are 
moveDragf ), sizeDragf ), and rotateDrag( J, and they are static 
procedures defined in shapeClass.c LineClass and polyClass 
inherit these procedures from shapeClass. 

To implement method inheritance, we either need a way for 
subclasses to get function pointers from their superclasses, or we 
need a way for superclasses to initialize function pointers for their 
subclasses. We will implement method inheritance the second of 
these two ways. Four requirements must be fulfilled for this to 
work. They are: 

1 . Each class which implements an inheritable method defines a 
special "inherit" symbol for the method, and the special 
symbol is made visible to subclasses. Subclasses which need 
to inherit a method place the special symbol in the function 
pointer member corresponding to the procedure to be inher- 
ited. 

2. Each class needs a setup( ) method which initializes the 
structure members for its class structure and the class struc- 
tures for its subclasses. 

3. Each class needs to keep a pointer to the class structure of its 
superclass so it can call the setup! ) method of its superclass. 

4. All method inheritance for a class and its superclasses must be 
resolved before any class methods other than setup! ) can be 
called. This requirement is met by calling a class's setup! ) 
method the first time one of its objects is created. 



Let's look at the polyClass structure to see how it is initial- 
ized, then step through code fragments from all three of our 
classes tosee how polyClass inherits moveDragO from shapeClass 
and inherits display) | from lineClass. Notice that almost all of 
polyClass's function pointer members are named "inherit... ." 
rhese are the names of the "special symbols" defined by 
shapeClass and lineClass so the methods they define can be 
inherited. They are the names of procedures which do nothing 
except return an error code. The "inherit..." procedures are de- 
clared in the private include file for a class, and defined in the 
class's source code file. Since subclasses include the private 
include file of their superclasses, the names of the dummy "in- 
herit" procedures are visible to them. Subclasses let their super- 
classes know which methods they want to inherit by placing 
pointers to the dummy procedures in their class structure. This is 
the class structure definition for polvClass: 



Inheritance 

1 1 w as mentioned above that all the procedures in a class are 
defined as static, and thus are not visible outside their definition 
file. This would seem to be a major flaw in object systems, since 
statu procedures cannot be shared among different classes, even 
subclasses of a class which defines a static procedure. However, 
object systems use a technique called "method inheritance" to 



- stiapeClass_p superCla^ 

(shapeClass_pU_lineClaas: 
polyClass_t .polyClass = 
I 



(class_p)4_lineCla83, /• superclass 

OX. • (lagWord 

sizoof (polyObject_u, /• objectSize 

/• methods specified by shapeClass 

setup, 

NULL, • initiflllM 
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■ 

" 
■ 
■ 

■ 

■ 
Dint. 



Method Inheritance is triggered when creaieShape( ) is 
called. For polygons, the class structure pointer sent to createShape 
is polyt lass. CreateShapef ) casts the class pointer to 
"shapeClass p and looks .it the flagWord member to see if the 
, lass has been initialized It not, the setupClassI ( procedure for 
the class Is called using the function pointer to the class's setup 
method. I leie is the code which does this: 

■ ■ ■ ; 

snap*" 

■ 



Since tin- class pointer sent to createShape points to 

polyClass, createShape( ) calls polyClass's setup method. 
Polyt lass keeps a pointei toitssupereIass(lineCIass),andafteril 
completes it-- setup processing, calls its superclass's setup method. 

sending its class pointer to it I lere is the code from polyClass's 

setup! ) method 



I! 8 



• 



LineClass defines a display method which draws polylines 
and polygons. This is the procedure polyClass wants lo inherit. 
I JneClass'sset up method examines the "display" function pointer 
member of the class pointer sent to it. If the display function 
pointer points to inheritDisplayl ), it is replaced with the pointer 
to the displayf) procedure defined by HneC lass. After lineClass's 
setup procedure finishes its processing, it calls shapeC lass's 
setup procedure: 

static int setup! class_p class I 

lineClass_p lineC = (lineClass_p)cJdgs; 

. .neC->display = = mheritDisplay ) 
HneC->display s display; 

(void) ("(superCIass->setupClass) ) (class) ; 
lineC->rlagWord I. IS.INITIALIZED; 
return 0; 



ShapeClass also defines a display method which can be 
inherited, so it also looks for a function pointer to inheritDisplayl 
). However, since the inheritDisplayl ) function pointer has 
already been replaced by a pointer to lineClass's display method, 
shapeClass does not find the inheritDisplay( ) pointer in the 
polyClass structure. ShapeClass's setup method looks for func- 
tion pointers to all the inherit...! ) procedures defined bv 
shapeClass, so it finds the pointer to inheritMovedrag{ ) in the 
polyClass structure It then replaces the inherit MoveDrag( ) 
function pointer with the pointer to the movedrag( ) procedure 
defined for shape objects: 

• setupt class_p class l 

shapeClass_p shapeC ■ ishapeClass_p)class; 

.nneritDisplay ) 
shapeC->di5play = display; 



■ ,; ■ 

■■■ ■■;■-■ 



.nhcntHovedrag I 
vedrag: 



■ riagWord 1= IS_!' 



return Of 



When shapeCIass's setup( ) procedure finishes, all the 
inherit...( ) function pointers in the polyClass structure have been 
replaced by procedures defined by either lineCIass or shapeClass. 
The way method inheritance works and can be implemented 
should be clear from this example. Its significance should also be 
apparent: very- little code is required to implement fully-func- 
tioning polygon objects, since almost all of their methods are 
inherited. 

You are probably wondering why such an elaborate scheme 
is used to implement inheritance. Why not just make class proce- 
dures visible to their subclasses, and let the subclasses explicitly 
initialize their own function pointers? The main reason we have 
implemented inheritance as illustrated is that subclasses can 
automatically inherit procedures without knowing which of their 
superclasses defines the inherited procedures. This technique 
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enables us to add new procedures to a class without having to 
change its subclasss's class structures. For example, suppose we 
define a moveDrag( ) procedure (or lineClass which will draw 
polylines as they are being dragged around, instead o( using 
shapeClass's moveDragf ) procedure which draws a box. The 
inheritance scheme we have implemented will result in polyClass. 
and also any future subclasses of lineClass, automatically inher- 
iting the new moveDragf ) procedure. Automatic inheritance is 
one of the reasons object-oriented systems are ideal for rapid 
prototyping: new objectclassescanbeimplemented quickly with 
very little new code. Later, when the new classes are working 
correctly, methods which are more appropriate for the new 
objects can be written to replace the methods which were inher- 
ited during prototyping. 

Object systems employ several other techniques which 
enable subclasses to use methods defined in their superclasses. 
One technique is "method chaining," and another technique is 
"superclass dispatching." Superclass dispatching occurs when a 
method in a subclass calls a corresponding method in its super- 
class. The example just discussed uses superclass dispatching: 
the setup! > procedure in each class calls the setup{ ) procedure of 
its superclass. Method chaining is more complex, and is best 
explained with an example. Method chaining is generally used 
when objects are created and destroyed. 

Creating and Destroying Objects 

All our graphical objects are dynamically created at run- 
time in dragAndlnsert( ). which calls createShape{ ) to actually 
create an object and return its pointer. Several steps have to occur 
when objects are created: first, memory for the object needs to be 
allocated; next, the object has to be "bound" to its class structure; 
finally, the object has to be initialized. Allocating memory for an 
object and binding it to its class structure is easy. Initializing an 
object is a bit tricky. Here is the object creation code from 
createShape()and from the static procedure initialize*) in shape.c 
which performs these steps: 

object_p createShapel class_p class ) 
I 

>ai_p ShapeC » getShapeClass(cla3Sl; 
shapeOb)ect_p shape ■ HULL; 

re owwry lor the otnec: •/ 

:.-ect_p)malloc (shapeC- >objectSiie); 

shape->class * class; 
shape->next = NULL; 

■ hf object •/ 

:bject_p) shape, class t » 

free( (void')shape I; 
return NULL: 



static int initialize* ob)ect_p object. class_p class ) 
I 

class_p super ■ getSuperClassiclassj ; 

ais_p shapeC = getShapeClasslclass); 

• recursively call self until we get to the root 



• class (has no superclass) 
V 

super I 
if i .super) ) 

/* call each class as we return from recursion »/ 

if t shapec .ze i 

return C (shapeC-> initialize) I (object); 
return 0: 



The only variable sent to createShapet ) is a pointer to the 
class structure for the object being created. As noted earlier, the 
class structure pointer is the menu "action data" for the "insert" 
menu item. CreateShape* ) casts the class structure pointer to a 
shapeClass pointer, allocates memory using the object size infor- 
mation stored in the class structure, and binds the new object to 
its class structure pointer. CreatcShape( ) then calls initialize) ) to 
take care of initializing the rest of the object's data values. The 
new object is initialized using method chaining: the initialize) J 
methods for the object's class and all its superclasses are called, 
from the "root class" (shapeClass) first down to the object's class. 
This form of method chaining is called "downward chaining." 
and it is used to permit every superclass to initialize the object 
structure members they are responsible for. The object's super- 
classes are called in superclass to subclass order so that each 
subclass can "override" (change) any values initialized by their 
superclasses. If a subclass does not need to perform any initializa- 
tion other than that done by its superclasses, it does not need to 
provide an initialize* ) method. Initialize) ) uses recursion to 
follow superclass pointers until it reaches the root class, 
shapeClass. As the recursive calls "unwind," initialize* ) calls the 
initialize method for each class which has one. 

Objects are destroyed in a similar manner, except "upward 
chaining" instead of downward chaining is used. When upward 
chaining is used, class methods are called in subclass to super- 
class order. Here is the object destruction procedure from shape.c 
showing how upward chaining is used when objects are de- 
stroyed: 

int dei j 'object ) 

I 

class_p class * getObjectClass! 'object) ,- 

shapeClass_p shapeC ■ get ShapeC las 



f 



* call superclasses in subclass to superclass order 

* to perform postdest ruction object cleanup. 



while ( shapeC 



I 



it ( shapeC->deallocate i 

(void) (• (shapeC- >dcal locate) ) ('object) ; 
shapeC = getShapeClass(shapeC->superClass) j 



I ree the object 

it ( 'object I 

freel (void') 'object t ; 
'object ■ NULLi 
;. 0; 
I 



• 



AC'S TEC H ,M 



Upward chaining occurs inside the "while" loop in 
deleteShape( ). The code looks at the deallocate function pointer 
in the class structure pointer, and it it is not NULL, calls it. Next, 
the pointer to the class's superclass structure pointer is retrieved, 
and if the superclass has a deallocate method, it is called. The 
while loop ends alter the root class (shapeClass) i- reached. 
DeleteShapet ) then frees the memory allocated for the object 
structure. 

Why are objects destroyed this way? Why not just free the 
memory allocated foranobject? Anyobjecl may contain pointers 
to internally-allocated memory, and if so, the internal memory 
needs to be (reed before the memory allocated for the object 
structure is freed. DeleteShape( ) does not know what kind of 
object is being destroyed, and does not know it it contains 
pointers to dynamically-allocated memory. Chaining through all 
the deallocate methods for a class and its superclasses insures thai 
any class which allocates memory fbi its objects can also free the 
memory before the object memor\ is meed. 

Object creation, initialization, and destruction are complex 

operations in object-oriented programming systems Many de- 
tails have to be taken care of to insure these operations are 
performed coin. Uj and completely. Two oilier complex opera 
lions are genericallv accessing and modifying an object's data 
values. 
Accessing and Updating Object Data Values 

PickAndEdit( ) calls getShapeValuesf ) to determine data 
values for an object so they can be displayed in our program's 
"Show/Edit" requester, and updateValues( )callssetShapeValucs( 
) to update an object's data \ allies alter they are modified. Both 
getShapeValuesf ) and setShapeValuesf ) use a technique whk h 
is common in object systems: an ana) ol structures containing 

tags "and values is tilled in and sent to a method which queries 
or modifies an object's value-- I he "tags" identity data elements 
which are to be returned or updated, and the "values" are either 
actual values or pointers to variables which hold the actual 
values. lags are identtliers which uniquely identify an object's 
data elements. They are detined in mam different ways by 
different object systems; sorneuseactualstrings.sorneusemacro 

definitions, and still others use hash functions to generate tags 

from data element names. Our program uses a simple technique 

HT.itmg tags. Each object structure member is assigned a 
unique name in the class responsible for the structure member, 
and a pointer to the string which points to the name is detined 
The pointer to the string pointer is exported as ,m "atom*' in the 
class's public include file, and is used as the data element tag. 
There are several advantages to this approach; it is simple; the 
compiler and linker will guarantee the tags are unique within a 
task; pointers can be directly compared for equality; and finally, 
the name can be accessed if needed. 

To make using tag-pointer value pairs easy, we define a 
structure to hold the pairs, and a macro tor setting up the array 
values. The definitions from globalDefs.fi are: 



typede! char •■atom_p; * • :■■ tag is an "atom* 



ier '/ 
value is bt *ned •/ 

void iPtrj '• pointer to value variable •/ 

* '-rg_p; 

■ 
(tarsi 

■ 

When we need lo query or modify an object's data values, 
we s,'t up an array of argj's, initialize the values, and call 
getShapeValuesf I or setShape Values! ) Here is a code fragment 
from pickAndtditl > which shows how the arg_t structure array 
and pointer variables are declared, how the array is initialized, 
and how getShapeVaIues( ) is called: 

arg_t 
doubli 

long 



■ 



set up the args array, then call get: 
g»tShapcValue6 will plao.- 

pointers corresponding ( 



a.ucs 



(void Ig 



fipyt; 



r. . . ; 

■ • • ■ 



GetShapeValuesf ) retrieves the object's 'get Values' method 
from itsclass structureand calls it to process the arg_t array Here 
is the code from shape class's get Values procedure which returns 
the class name for shape objects: 

\-_om I 

strcpy ' " -Nap«"t: 

nuej 



There are two weaknesses in using tag-pointer pairs to 
access and update data values for objects: first, the tags which a 
i lass oi objit ts recognizes must be known; and second, the value 
pointers must be the correct data type and data si/e. For example, 
to access an object's class name, our mini-CAD application needs 
to know that all objects recogni/e"class\ l ameAtom"asa tag, and 
that the type of value associated with the tag is a character array 
which can hold a maximum of 32 characters. The first weakness 
is minor, since a class which does not recognize an atom just 
prints an error message and ignores it. The second weakness can 
have serious side effects (memory corruption) if a value is as- 
signed to a data type which has too few bytes to hold the value. 
1 he tags tor a class and its subclasses are made known to appli- 
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cationcode by being declared in theclass's public include file. The 
associated data types for the lag value pointers are placed in 
comments next to the lags, and applications querying or updat- 
ing object data valuesare responsible (or makingsure the pointed- 
to variables are the correct type and size. Here are how the 
declarations from shapeClass. h for classNameAtom and 
xLocationAtom look: 

extern const atom_p classNameAtom; /• char*. 32 bytes •/ 
extern const atom_p xLocationAtom; /• double ■/ 

Finally, here is how classNameAtom is defined in 
shapeClass.c 

static char •const _classNamc - "className"; 

const atom_p classNameAtom ■ (ar.orr._pit_className: 

Modifying an object's values is more complicated than 
accessing its values. The valuesare modified in basically the same 
way they are accessed However, after the values are modified, 
the object needs to know which ones were modified so it can 
perform any actions required because of the modifications. As an 
example, when the width and height values for objects are 
changed to negative values, they need to be scaled (to flip them) 
and moved back to their original locations. Additionally, sub- 
class objects may need to disallow some modifications which 
their superclass objects allow. Because of these considerations, 
selling an object's values using tag-value pointer pairs is a two- 
step process. Modifying the object's values occurs first. After this 
is complete, an "update" method for the object is called and sent 
Ihe modified object, along with an unmodified copy of it. The 
object's update method then compares its new values with its old 
values to determine which values changed. The update method 
can disallow changes by setting the modified values back to their 
original values, allow some values to change, or allow all values 
to change. Based on which values changed, Ihe update method 
can perform any additional processing needed to insure the 
integrity of the object is maintained. The following code from 
setShapeValues( } shows how this two-step process is done 



■ 

1 crtflt .low copy of the unmodified object 

* The copy is used by the class to determine which 
' object values were changed. 

*/ 

copy = lobject_p)malloc<shapeC->obJcctSize); 
■te»cpyHvoid")CDpy, ivoid'>object.shapeC->objectSize) ; 
/• set the object values •/ 

(void! ('(shap* t.args.n); 



* send the updated object and the unmodified copy 

* to the class so it can validate the modifications 

any actions needed to maintain 
■ the integrity of the object 

• 

.■ipeC->update) Mobject.copy, window) .- 
free( (void'icopy ) ; 
return ret; 



You can look at the setvalues and update methods in both 
shapeClass.c and lineClass.c to see how objects are modified and 
see the types of actions required when an object's values are 
changed. 

Other than the procedures for creating and destroying 
objects, and for accessing and updating an object's data values, 
the rest of the procedures in shape.c, line.c and the three class 
modules are relatively easy to understand. In fact, the procedures 
in the class modules are basically the same ones presented and 
discussed in Part II of this series. 

Summary 

In Part 1 of this series of articles, I promised that we would 
develop a basic CAD program. We have almost achieved that 
goal: we developed a library of transform procedures and a set 
of procedures and techniques for handling Intuition's input 
events in Part 1 and Part 2. In this article, we developed a 
framework for implementing geometric models using object- 
oriented programming techniques, and saw how to implement 
several classes of geometric objects. In my next article, we will see 
how new classes of objects are implemented using our object- 
oriented framework, and add rectangles, circles, and ellipses to 
our mini-CAD application. We will then have a mini-CAD pro- 
gram which can be easily extended to include both new objects 
and new functionality. 



Listing One shapeClassP h 



■ 






Listing 1. Private include file for shapeClass. 



• shapeClassP. h - defines class structure and ob)ect 
' structure for shapes. 

' The structures defined here are common to all 

' geometric classes and objects. New class and object 

• structures are created by overloading (extending) the 

• shapeClass and shapeObJect structures defined here. 

• 

" Id Copyright 1991. Forest w. Arnold 

• All rights reserved. 



■ «•■■! 






Ilfndef SHAPECLASS P_DEFS 
•define SHAPECLASSP_DEFS 

•include •globalDefs.tr 
•include "shopeClass.h' 



class flag values 



•define IS_INITIALIZED 1 



Shape Class Part - defines the shape class part 

of a shapeClass structure. The CLASS_PART 

consists of information about the class and its 

objects, and a 'setup' procedure which 

to complete initializing the class structui 

when the first object is created. 

The SHAPEC.PART consists of function pointers 

to the methods for a class. 
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■define CLASS_PART \ 

class_p ;;erClass;\ 

unsigned long UagWord;\ 
unsigned int objectSize;\ 
int CsetupClaBS) (class_pi ; 

•define SHAPEC.PART \ 

int • zel(object_p);\ 

int ('deallocate) lobject_p);\ 

■ etvalue) (object_p.arg_p, Int) ; \ 
int Cgetvalue) ( object _p.arg_p. int) ;\ 
int ('update) lobject_p.object_p.window_p) ;\ 
int fdisplayl lobject_p.window_p 
int Cerasel (object_p ,window_p 
int ("highlight) (object_p.wir.dow_p |;\ 
int t'unhighlight) (object_p.window_p i;\ 
int Cinsertdragl tobject_p.window_p );\ 
int I'movedrag) I object_p.window_p«\ 

double '.double ■ );\ 
int ("sizedrag) ( object_p,windowj>, double, double, \ 

double '.double • );\ 
int I'rotatedrag) (object_p. window_p. double, double, \ 

double ');\ 
int I 'move) <object_p. double. double) ;\ 

*o) (object _p, double, double, double. double) j\ 
int t "rotate) <object_p, double. double, double) ;\ 
double I'pointToObject I lobject_p. double, double) ; \ 
int ('extent) (obJect_p,double '.double ",\ 
double ".double ■) i 



This is the shape class structure definition. 
All classes which are subclasses of shapeciass 
will consist of CLASS_PART and SHAPEC_PART as 
the first two parts of the class. 



typedef struct _shapeC 
I 

CLASS.PART 

SHAPEC_PART 
( shapeClass_t.'shapeClass_p: 



given an instance of a class_p, these macros will 
access the shape class i the shape superclass 



•define getShapeClass (class! \ 

((class) ? IshapeCIassji) (class) : NULL) 

•define gctSuperClass (class) \ 

((class) 3 l (shapcClass_p) (class) I ->superClass : HUI 



shapeObject structure definition 
All shapeObjects and objects whose class is 
a subclass of shapeClass will consist of an 
OBJECT_PART and a SHAPE_PART as the first two 
parts of the object. 



typedef struct .shapeObject 



OBJECT_PART 
SHAPE_PART 
) shapeObject_t."shapeObject_p; 



define some convenience macros for accessing the parts 
sanely. 



•define getObjectClasslobjec: 

((object) ? KshapeObject_p) (object ))->class : NULL ) 



symbols defined by shapeClass for method inheritance. 
These are dummy procedures. The procedure names are 
used as function pointers in the appropriate subclass 
method slot instead of a 'real' procedure. During 
class setup. shapeClass checks tor these symbol. 

•>y are found, they are replaced by the actual 
shapeClass function pointer. 



extern shapeClass_t .shapeClass; 



■xtsrn 

extern 
extern 
extern 
extern 
extern 



int inherit Display I object _p.window_p )j 

int inheritErasel object_p, window_p ); 

int InhcritHighlight ( object_p.window_p ); 

int inheritUnhighlight I object_p.window_p ); 



int inheritlnsertdragi objcct_p.window_p | ; 
int inheritHovedragl object_p,window_p. 
double*, double' ); 
extern int inheritSizedragi object_p,window_p. 

double. double, 
double', double* ): 
extern int inheritRotatedragl object_p.window_p. 

double. double. double* ); 
int inheritHove( object_p, double, double ); 
int inhentResizel object_p, double. double, 

double, double I; 
int inheritRotate) object_p, double. double, double ) 
double inheritPointToObject (object _p, 

double, double) j 
int inhentExtent ( object_p. double'. double*, 
double'. doublr* 



extern 
extern 



extern 
extern 



■xttrn 



'/ 



This is the shape object definition. The class 
neaber is a 'handle' to the object's class and 
methods. 

Erst member in any object is a pointer to 
the class structure which contains the methods 
for the object. 

The SHAPE_PART contains members specific to all 
geometric shape objects. 

■inx.miny.maxx.maxy are coordinates of the 
bounding box for any object. 



iMdif 



•define OBJECT_PART \ 
class_p class; v 

void "next; 

•define 5HAPE_PART \ 

double minx.miny.-\ 

double maxx.maxy; 



SHAPECLASSP_DEFS 



Listing Two ImeClassP.h 



Listing 2. Private include file for lineClass. 

lineClassP.h • lineClass extends shapeClass to include 
tl hods for finding, dragging, and 
moving the individual points in a 
line. 



The structure for line objects extends 
the shape object structure to include 
a pointer to the list of points in the 
object. 



(c) Copyright 1991. Forest W, Arnold 
All rights reserved. 



tUstings 1-7 can be found on the AC'S TECH Disk) 
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* 

•Ifndef LINECLASSP_DEPS 
•define LINECLASSP.DEFS 

• . 
•include 'shape 
•tnclud- 



' draggmj. 

• 

• do: me lihec.part \ 
point_p (*findPo;nt l (object 
(•dragPoint ( i 

('■ovePoint I I 

■ 
• 

• str . ■■•:.. :: 

• structure. 



typedcf struct. _UneC 
( 

CLASS.PART 

SHAPEC_PAHT 

■ 



* Line Object Part - line 

* points to shape object. 

* coordinates of the line. 



* 



iods for finding, 












.1 by "ovei shape 

LINE_PAPT is added to the end of 
shape object :■ 









,PART 
PART 

1 ' ect_Pj 



■ 



• 



a clas5_p 



I 



i 



• external do subclassei 

• export . and 

cedures. 

• 

. eClass; 

* 



lass. 
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Implementing 

an ARexx Interface in your 

C Program 



By now. I am sure lh.n many Amiga users have heard 
about ARexx and are well-aware of ihe capabilities ot this macro 
language. I will not repeat the same information here. You will 
need some degree of familiarity with ARexx and a fairly good 
working knowledge of C to put the information presented in this 
article to good use. If you are not that familiar with ARexx or C a 
study of those languages will help you understand this article 
belter. 

Misconceptions 

Before I began working with ARexx, I had some miscon- 
ceptions concerning implementing an ARexx interface in my own 
programs. I believe other programmers also have some of these 
misconceptions. The following paragraphs will cover some of 
these possible misconceptions. 

At first. 1 thought that it would be too difficult to add an 
ARexx interface lo a program I had written Thai turned oul lo be 
false, but that was mostly because of my programming style. There 
are programming styles that are conducive to adding an ARexx 
interface and there are programming styles that make it quite 
laborious. 1 am not suggesting that one style is correct and another 
style is incorrect— it is simply a matter of preference. However, 
when it comes to adding an ARexx interface, your programming 
style can save you programming time or Increase il. 

If you are a programmer that believes in the structured 
approach lo programming, you should have little difficulty add- 
ing a ARexx interface to your programs. Structured programming 
uses separate functions lo execute the subtasks that the program 
requires to perform its job. Each function is kept as small as 
possible to do ils particular subtask. The structured programmer 
then includes calls lo Ihese functions within Ihe C programming 
constructs such as the switch, if-else, do, while, and for statements 
When adding an ARexx interface, it is just a matter of calling the 
proper function to perform Ihe subtask required to fulfill the 
command requested by an ARexx message. This is the most 
efficient programming style when it comes lo adding an ARexx 
interface. Some very good articles describing the structured pro- 
gramming approach to programming have been written by Paul 
Castonguay in previous AC TECH issues. 

Thealternativetotheslructuredprogrammingapproach 
is lo include Ihe code thai executes each subtask within the C 
programming constructs mentioned earlier. Each case within a 



switch construct contains thecode required to perform a particular 
subtask rather than calling a function, for example. If this type of 
programming is your style, you will need to add functions to your 
program lo execute when you start receiving commands in the 
form of ARexx messages. Redundant programming results since 
most of the instructions contained in the switch statement are 
going to be almost exactly the same as in the functions you have to 
add to execute the ARexx command requests. This is the least 
efficient programming style when it comes lo adding an ARexx 
interface. 

So you see, the difficulty you experience in implement- 
ing an ARexx interface in your program has much to do with your 
style, or approach lo programming. If you are considering writing 
a program in which you would like to include an ARexx interface, 
Ihen you might wanl lo consider using a structured approach to 
programming. You should write each command so that you call it 
in exactly the same manner whether the source of (he request is 
from your ARexx interface or from any other source. 

Another misconception some public domain and 
shareware programmers might have is that they don't need to put 
an ARexx interface in their programs because not too many Amiga 
owners have ARexx. Some time ago lhat might have been true, but 
consider this: when Amiga owners upgrade lo Amiga DOS2.0,and 
almost every Amiga owner will inevitably wanl (o, they will all 
have ARexx. Even now I suspect a large number of the Amiga 
Owner? have ARexx. If it were not so, Ihe commercial software 
houses would not feel compelled lo include ARexx interfaces in 
their programs. Public domain and shareware programs, some of 
which are every bit as good as their commercial counterparts, can 
also benefit from an ARexx interface. Imagine Amiga power users 
combining the use of your program with the commercial programs 
Ihey have. 

If you're concerned about the increase in the size of your 
program, you have no need to worry. Again, your style of pro- 
gramming determines this. If you write redundant code to imple- 
ment each command your program can perform, your code si/e is 
going to increase much more than if you write functions lhat you 
can call from any location in your program. So. not only can your 
programming style determine the difficulty you are going to have 
including an ARexx interface, but il will also determine the size of 
the additional code you will need lo write to have an ARexx 
interface in your program. 
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Reasons for an ARexx Interface 

I have already touched on some of the reasons why you 
might want to add an ARexx interlace. If you area public domain or 
shareware programmer, you obviouslv want vour program to be 
used and enjoyed. Anything you can add to your program thai will 
increase its usefulness will ensure that it does gel used. An ARexx 
interface does increase the utility of your program. Even if you're 
simply writing a program for your own personal need, an ARexx 
interface will enhance its usefulness. However, it vou write a pro- 
gram for your own personal need that you get considerable use out 
of, I would suggest introducing It into the public domain or releasing 
it as shareware. 

Consider how your program could perform when com- 
bined with a high quality commercial, public domain, or shareware 
program. You could write an ARexx macro program that would 
unify the two programs. You coutd easily switch between the pro- 
grams in memory making it appear as one unified programming 
environment. Staggering possibilities flood my imagination 

This type of program integration mav also save you pro- 
gramming time You may want to write a program that modi he> the 
output of another program to suit your specific needs. If bolh pro- 
grams have an ARexx interface, you are all set. You can then concen- 
trate your work on the code to perform the modification and let the 
other program handle the initial work. 

Sure, you could also accomplish this without each program 
containing an ARexx interface. This would require you to run one 
program and perform the work you want to do. After you had 
finished with the first program, you would run your own program to 
modify the output of the first program. That's not too much trouble. 
I guess, if you're used to that kind of juggling with your programs 
However, 1 think that the idea of multi-tasking two or more programs 
under the control of a macro program is much more attractive. Both 
programs could be working on the same data to produce the final 
output that you want. This is what most Amiga owners are used to. 
This is the reason for a macro language like ARexx. 

Another good reason for an ARexx interface is the control 
it gives the user over your program. Many software companies are 
going to great lengths in their advertising to inform Amiga owners 
and potential software purchasers when their products contain an 
ARexx interface. I believe they realize that the potential to tailor their 
program to the user's specific needs is very attractive to the user. 
Whenever I look at a new software package to buy, one of the first 
things I look for is an ARexx interface. I might not be able to make use 
oi it right away, but 1 mav eventually put it to good use It vou are 
producing a program with commercial or shareware potential, an 
ARexx interface may translate into monetary gains. If you are pro- 
ducing a program that you intend to release into the public domain, 
an ARexx interface may be just what you need to persuade people to 
try your program. Whether you are going for income or for the 
personal satisfaction of knowing that your program is being put to 
good use, an ARexx interface can help. 

One final reason for an ARexx interface: support for the 
ARexx language is continuing to grow. Recently I have seen two new 
products that expand the ARexx language as released by Bill Hawes. 
One is an object-oriented programming tool and the other is an 
ARexx compiler. With the growth of support will most likely come. in 



increase in interest by common Amiga owner* Nhmv tor .1 software 
package to be successful, I believe thai an ARexx interlace will be 
essential. 

Programming the Interface 

llu- following description oi the steps required to add an 
interface will give vou what you need to get started I he interface can 

be '»s simple or as complex OS VOU want to make 1! 1 he more complex 

of an interface vou want However. Aeinore programming you will 

do to implement it 1 will give v«u the basics ami then II is up to vou 
lO determine how far vou want to go with them 

The very first thing you must do Is open thcrexxsys llbrar) 
through a call to the Exec's Openl.ibrary function You must put the 
return value from this function into I global variable named 
RewSvsliase After you have opened the library, vou haveaccess to 
all the ARexx system functions I will not cover these functions since 
that would take too long, and thev an? all well covered in Appendix 
C of the ARexx User's Reference Manual. 

Getting! message port up and running should be your next 
priority. The easiest way to accomplish that is bv using the Exec's 
CrealePort function (a complete description of this function can In- 
found in the version J i ROM Kernal Reference Manual: Libraries and 

t, page 281 oronpageB-5ol the version 1 2 Exec RKM), ihe 

v re.itePort function will allocateall the necessarv memory. add vour 
port to the 1'xec's public port list, and allocates a Signal bit fOTUSC With 
this message port. This message purl can be considered the hub of 
your interface. Command requests, information requests, and replies 
to messages you sent out will come through this message port All ol 
your interaction with ARexx and any other ARexx host program or 
macro will go through this message port Because this message port 
is vital to the execution of your interface, it is important that you keep 
up with its activity. 

Most likely, your program will be receiving input from 
some source, and your program will probablj be waiting foi some 
event to occur before it can proceed with processing litis will most 
likely be in one form of the Wait function or another Adding yoin 
port signal to the list of signals vou are waiting on is simple and 
something you are probablv already familiar with. If vou are untam il- 
ia r with the Wait function or how to set up to wait tor multiple signals, 
vou can reler to the main function of the I ilcr.v source code (Listing 
Two). Toward the end of the mam function, 1 set up the signals I am 
going to wait on. and then in the while loop that follows, 1 wail on 

certain signals to occur. After my program wakes up, I test the return 

value from the Wait function lo determine which signal woke up my 

program. 

The alternative to waiting on signals to wake up vour 
program is to create a bus\ loop .nut check your message port 
periodically toseeil there is a message mailing. However, tins type 
of programming is not considered appropriate in a multitasking 
operating system I his generally slows down the s\ stem and irritates 
many users. Therefore. I recommend the first procedure. 

When your program wake's up and vou have determined 
that the signal you allocated for vour ARexx message port is the 
culprit, you need to get the new message .m^\ process it Call the 
Exec's Get Msg function to get the address of the RexxMsg structure. 
(Refer to Figure One for the RexxMsg sir m Hire definition .1 Now that 
you have the RexxMsg structure addTOSS vou can determine what is 
being requested ol vour program. 



"If you are producing a program with commercial or slwreware potential, an ARexx 
interface may translate into monetary gains. 
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The request will be contained in the 
rm_Arps|01 field, also known as ARCO, of the RexxMsg 
structure. This is the RexxArg structure that contains 
the command name (your program name) and the 
arguments that go with il. (Refer to Figure Two for the 
RexxArg structure definition.) The value contained in 
ARCO can be treated like a pointer to a C style null- 
terminated string since that is basically what it is. All the 
fields in the RexxArg structure can be accessed at nega- 
tive offsets from this pointer. However, this string is 
what contains all the information you arc looking for 
The first argument is the command name. You use this 
to determine which function to call. The remainder of 
the string should be parsed and sent to the function that 
executes the requested action. It is the information 
following the command name that you will need to 
extract from this string All arguments are sent in string 
form. If you are expecting numeric arguments, you will 
need to use some of the C standard library functions to 
convert them to the format you require. There is a 
special condition that you need to be aware of This 
occurs when the macro programmer requests tha t ARexx 
do the parsing for you. 

Since you are fust writing the host application 
and not every macro that could possibly call your 
program, you need to be aware that not every macro 
needs to call your program in exactly the same manner. 
To restrict the manner in which your program may be 
addressed by other programs is considered quite rude 
in some programming circles. What I am getting at is 
that a macro programmer can request that ARexx 
tokenize the command string prior to sending the 
RexxMsg structure to your program. The programmer 
does this by setting the RXFB_TOKEN command modi- 
fier flag bit in the rm_Action field of his or her RexxMsg 
structure. (Figure Three contains a complete listing of 
theCommand modifier flagbits.) When ARexx receives 
a message structure with this bit set, it breaks up the 
ARCO string intoseparalestringsandcreatesa RexxArg 
structure for each oneand places them in the rm_ Args[0- 
15],ARGO-ARG!5,heldsin the order they appear in the 
command string. Tocorrectly handle this situation, you 
need onlt to check the RXFB_TOKEN bit, and if it is set, 
get your arguments from the individual rm_Args(] 
fields and convert them as needed. To determine how 
many arguments the command string had, check the 
lowest nibble of the rm_ Action field. This will be set to 
the number of arguments. If the command string has 
not been tokenized, then you will need to parse it «is 
previously explained. 

Once you have parsed the command and 
processed the request, you reply to the message. The 
important thing here is to report on the result of your 
processing so the program that sent the message can 
know what action to take. If all went well, set the 
rm.Resultl field to RC_OK. (See Figure Four for the 
ARexx return codes.) The rm_Result2 field is used to 
return a pointer to the result string if the RXFB.RESULT 
command modifier bit is set. The return string must be 
in the form of a RexxArg string. A result string should 
be returned only if requested and no errors occurred 
during you processing. If you were unsuccessful in 
your attempt to process the request, you set the 
rm_Resultl field with severity level of the error and the 
rm Result2 field should be set to zero. 
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RexxArg Structure Definition 
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Table One 

Command Modifier Flag Bits 


RXFB NOIO 
RXFB RESULT 
RXFB STRING 
RXFB TOKEN 
RXFB NONRET 


Suppress I/O inheritance 
Result string expected 
Program is a string file 
Tokenize the command line 
A non-return message 



Figure Three 

ARexx Return Codes tor General Use 



RC FAIL -1 


Something's wrong 


RC OK 


Success 


RC WARN 5 


Warning only 


RC ERROR 10 


Something's wrong 


RC FATAL 20 


Complete or severe failure 


Figure Four 




Rexx Data Structure 
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Not every message received at your message port is .1 
request for some sort of action. With only one exception, if you send 
any messages to the ARexx resident process, you can expect to 
even tually receive reply messages. When these repliesstart rolling in. 
you need to be able lo distinguish between them and requests for 
information or command requests. This is a fairly straightforward 
procedure. You check to see if the message you just retrieved is the 
r-.;v\I KIT! YMSC rhiswillbeintheL'BYTf : ln lype field in the 
rm_Node message structure in your RexxMsg message structure. 
The test could look like this: 

■'Hens«g«->n*_Node.tnn_Node.ln_Typ« "^ rrr_BEPLYMSGI 

When you do determine that it is a reply message, check for 
possible error conditions and handle any that appear. If all went well 
and you requested a return string, you need to extract the return 
string, delete any RexxArg's and then delete the RexxMsg itself. If 
you did receive a return string, you are responsible to delete this 
RexxArg structure when you are done with it 

Another way todistinguish between requests and replies is 
to set up .1 separate message pott for replies only. Put the address of 
this message port in the mn_ReplyPort field of the RexxMsg message 
structure. 

MyMeBsaoe->m_Hod*.nm_ReplyPort : HyReplyPort: 

Now, when the message returns to you it will come back to your reply 
port, and you can have a customized function to handle all reply 
messages received at this port. Your other ARexx message port will 
only receive requests of one kind or another and can have its own 
(unction to send off those request to your program. The way you 
handle your message traffic is up lo you. Each way has its pros and 
cons. 

Earlier I referred lo the fact that some messages you send 
out may not come back in the form of a reply message. If you set the 
RXFB_NONRET command modifier flag bit in the RexxMsg 
rm_Aelion field, you will never hear from that message again. Maybe 
thai is a good idea What happens, however, it the action you 
requested is not successfully completed? You may never know. Live 
on the edge; try it. 

So far I have just written about commands received from 
other programs instructing your program on what to do. However, 
you can direct other programs through your ARexx interface also. 
You can get ARexx macros running. You can run other host applica- 
tions. You can exchange information with other host applications. 
You can even combine these possibilities in new and imaginative 
ways. All of your communications with exterior program*, however, 
should go through the ARexx resident process. That requires you to 
get an ARexx message put together with the proper initialization of 
the fields that are required to get the message to the proper destina- 
tion. 

The first thing you have to do, of course, is allocate some 
memory for the RexxMsg structure. I generally request that the 
memory be cleared as it is allocated (ex., MyRexxMsg = 
AllocMem(sizeof(strucI RexxMsg), MEMF.CLEAR) ). This has the 
effect of initializing all the unused RexxMsg fields for you. All you 
have to do then i> set up the fields you are using. The rm_ Action field 
is extremely important. This is the action code (command) you are 
sending to ARexx. There are a number of these action axles, but we 
will focus on the command-level invocation code (RXCOMM). As 
previously covered, there are some command modifier flag bits that 
can be set in the rm_Action field to further tailor the action code. 
These command modifier flag bits can be combined to finely tweak 



the command execution. However, setting the RXFB_NONRET and 
the RXFB_RESULT biisat the same time may have some serious side 
effects. The first bit instructs ARexx not to return the message to you 
and the second bit requests that a result string be returned in the 
message structure that you just requested not be returned. (What a 
paradox for AKexx I am not exactly sure what would happen.) Next 
you place your message port's address in the MN_REPLYPORTand 
rm_PassPort fields of your message structure. Then you put the 
pointer to your message port's name in the MN_NAME and the 
rm_CommAddr fields. Optionally, you can supply a file extension 
for ARexx to use when looking for the command name you sent to be 
executed by placinga pointer toafilcextension string in the rm_FileExt 
field, and you can send your program's default input and output 
filehandles by placing them in the rm_Stdin and rm_Stdout fields 
respectively. 

As described, the task of implementing an ARexx interface 
seems quite imposing. There are quit a few minor details that must be 
attended to. The task is simple enough, but allocating and releasing 
memory for ARexx messagesand argstringscan take its toll. Creating 
a message port for your interface to use, monitoring the message 
port's activity, parsing the command strings, distinguishing between 
command requests and reply messages, all the tasks associated with 
sending a command to ARexx and finally deleting your message port 
when you arc done with it can be a nuisance. Don't get me wrong, an 
ARexx interface is worth all you go through to have it. On the other 
hand, if most of the tedious work was done for you, wouldn't you 
want to take advantage of that? 

RexxappMbrary Answers the Call 

That is exactly what Jeff Glart of Dissidents Software has 
done. He has put together a library of functions that will take care of 
all the mundane tasks associated with an ARexx interface. This is the 
rexxapp.library. 

This library automatically handlesall of the message traffic 
associated with your ARexx message port. It accepts asynchronous 
ARexx messages and sends both synchronous and asynchronous 
messages to ARexx on behalf of your program. This means that you 
can control other programs or be controlled by other programs 
through this library. 

The rexxapp.library allocates and frees the memory for all 
the ARexx structures it uses. You no longer work directly with the 
ARexx resident process. You don't have to supply the routines to 
handlea message port. You give the library a message port name.and 
it opens the message port. The library creates all the ARexx messages 
and sends them out at your request. It also distinguishes between 
commands received and replies to messages you sent out. It can even 
call separate routines based on whether a reply message returns a 
result string or an error condition. All this processing power is packed 
into just seven functions. 

This limited number of functions means that with very little 
programming you can have an ARexx interface. To take advantageof 
the library, first set up the RexxData structure defined by Jeff C'.latt 
for use by the library. (See Figure Five for the RexxData structure.) 

RexxData Structure 

The RexxData structure is a required argument for every 
function in Ihe library. It is a variable length structure. The size of the 
structure varies with the number of commands your program recog- 
nizes You supply the number of commands in the NUMCMDS 
variable in your header file. This variable must be defined before you 
declare the RexxData structure type. You must initialize the Exten, 
Func, Error, Result and AsscListj| fields of your RexxData structure 
before you can use it. 
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The l-xten field holds.i pointer to the null-terminated string 
to use as the fUename extension to affix to commands received by the 

library that are not in your asso ci ated command list. This situation 
can happen if the ARexx address command, followed bv your port 
name, precedes a command the AKevv in t e r pre te r does not under- 
stand. The ARexx interpreter will package this command up as an 
argstring, place a pointer to ibis argstring in the AKC'iO field of a 
RexxMsg structure and send this message to your program for 
processing. If this command is actually the name of an ARexx macro, 
and not an internal command of your program, the library adds the 
filename extension to it and sends the message back to the ARexx 
resident process H I command invocation request. ARexx will then 
run the macro for your. With this feature, you can USeARexx macros 
in thesamefashionas internal commands. If you don't really want an 
extension but you would like to take advantage ot this feature, put a 
pointer to a nulled string in this field. The library will pass the 
command on to ARexx exactly as received. By placing a zero in this 
field you turn this feature off. That means that when the library 
encountersa message sent to your message port, that does not contain 
a command in your associated command list, it will be returned to 
ARexx with an error value of 30 in the rm_Resultl field. 

The Func.Errorand Result tiel.ls hold pointers to functions. 
You write these functions, and the library calls them to handle » ertain 
situations. Writing these three functions is probabl) the most work 
you will do in setting up your interface using the revxapp.library. 

The Tunc field holds a pointer to the function you want the 
library to call when a message arrives at your message port that has 
a command in the argstring that is also found in your associated 
command list. Dispatch is the name ol mv (unction The library calls 
this function only when your program calls the ReceiveKew library 
function (more on the ReceivcRexx function later) The dispatch 
function receives four arguments: a pointer to the message that 
prompted the call, the pointer to the function to call to execute the 
requested command, a pointer to the argstring stripped of the com- 
mand name, and a pointer to your RexxData structure. Tins function 
should set up any arguments or variables that the requested function 
needs and then calls the function. When the function you called 
returns, you need to set up the result fields using the message pointer 
you received in your dispatch function's first argument. The result 
fields are set up differently depending on whether the command was 
executed successfully or not. The library's SetupResults function 
gives you a convenient way to set up the result fields (again, more on 
the SetupResults function later). After vour dispatch function isdone, 
youreturneitheraoneora/ero. A return value of one tells the librarv 
to reply to the message. A return value of zero tells the librarv that 
your program is going to reply to the message. Unless you absolutely 
need to hold onto the message for some reason, you should let the 
library reply to the message One side effect of holding onto the 
message is that the ARexx script thai sent the message is suspended, 
put to sleep in other words, until you replv to the message. 

The Error field holdsa pointer to the function for the library 
to call whenever any message that your program sends out returns 
with ,ir\ error. Most likely this function will ]ust print the error 
message to the screen, in one manner or another, to let the user know 
that an error occurred. If you don't want to do anything with error 
returns, you must still provide a dummy routine. Yourcrror function 
receives four arguments: the error code, a pointer to the enrol string. 
a pointer to the message that returned with an error and a pointer to 
your RexxData structure. Do not alter the error string 

The Result field holds a pointer to the function for the 
library tocall whenever any message your program sendsout returns 
after a successful completion. What your functions does with the 
result string depends on which function in your program sent the 
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message in the Brst place ii you never request a result string to be 

returned, mhi slill need lo provide .i dummy routine. Your result 
function receives lour arguments: Ihe result code, a pointer to the 
result string, a pointer lo Ihe message thai has relumed and a pointer 
to your RexxData structure. Do not alter the result siring. 

You can find the prototypes to my functions in Listing One, 
my header Hie, and you can see Ihe actual code in Listing Two, my 
source code. Tlie names nl mv functions are dispatch, error_rtn and 
process_rtn. In this article, mv dispatch routine is a scaled down 
routine. In Part Two of this article. 1 will add more to this routine to 
make it a little more useful. My error routine, enor^rln, simply 
displays! in. intorequester to Ihe window to inform the user what has 
happened. My return function, process_rtn, is just a dummy routine 
in this program I never request a result string However, in the 
completed program that will accompany Part Two of this article, this 
routine may change if needed 

The last field vou Initialize in the RexxData structure is the 
AsscLisl|) field. Tins is an am) of C mdFntry structures. Fach com- 
mand entry structure contains a name string of a command your 
program recogni/es and a pointer to the lunclion that is associated 
with this command string. The variable NUMCMDS defines the 
number of commands in your list The las! entry in the lis! must be a 
NULL entry so the NUMCMDS variable musi actually equal the 
number of commands your program recognizes, plus one AH the 
commands must be in lower-case letters with no imbedded spaces. 
The library does nol require ihe complete command string in order to 
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match a command request to the command list entry llnneot youl 
commands in your list is open, then the string ope will also result in 
a match. Be sure to make all of your command names unique Am 
command of yours that matches an ARexx instruction will be M-nl to 
the ARexx interpreter instead of to your program 

Now let's go over the functions available for you to use in 
the library. There are only seven functions to cover SetRexxI'ort, 
ReceiveRexx, SetupResults, FreeRexxPort, SendRexxCmd, 
SyncRexxCmd and ASyncRexxCmd. 



SeiRexxPort 

The Set RexxPort function must be called I irst. I his (unction 

doesallyour Interface set up You pus it a pointer to your port name 

and a pointer to your RexxData structure I His function returns a 
signal bit mask assigned to your message port. You can use this mask 
in the Exec Wait function to wail lor. icth \\\ al this message port The 
port name string butter should be one byte larger than the actual 
name. This function appends a number between 2- u on the end of 
your port name to resolve any conflicts with port names already used. 
The library can support only up to nine copies of your program 
running at once. This function will initialize the remaining fields in 
your RexxData structure. You call this function only once. This 
function returns a zero it it was unsmvessfiil. Once you have success 
ful set up. you are ready to continue. 

ReceiveRexx 

The ReceiveRexx function is the workhorse ol the librarv 
When a message arrives at your message port, your program is 
awakened by a return from the Wail (unction. When you test the 
return value and determine that the signal trom your ARexx message 
port caused your program tobecome ac tive.vou cat I the Receive Rex x 
function. The ReceiveRexx function takes care of all the messages 
waiting at your message port. It can tell the difference between 
commands received from other programs and replies to messages 
you initiated. If the message is a command, ReceiveRexx will call 
your dispatch function. If the message is a reply, ReceiveRexx checks 
the rm.Rcsultl field of the message structure to see if the request h is 
executed successfully. ReceiveRexx calls your result lunclion it ev- 
erything went well; otherwise, it calls your error function. This 
function frees the memory used by messages you sent out anil replies 
to all messages that your message port receives The only lime it will 
not reply to a message is if your dispatch function returns a zero 
Before your dispatch function returns, howev er. it should havecalled 
the SetupReslls function. 

SetupResults 

The SetupResults t unction is used by you to communicate 
to the initialing program whether its request was successfully com- 
pleted. You provide a primary result value, a secondary result value. 
a pointer to a return string, a pointer to the message structure that 
caused the action and a pointer to your RexxData structure It the 
request was successful, pass a zero as IhiiIi the primary and secondary 
result values, and you pass a pointer to a result string if the 
RXFB_RESULTcommand modifier hit is sit II tlu-RXFB.RESULTbit 
is not set or you don't have a siring to return, you supply a NULL as 
a result string pointer. You return the pointer to the messagestructure 
that ReceiveRexx supplied. You return error values fitting the error 
severity level in both the primary and secondary 1 result values and a 
NULL as the result string pointer if youdid not successfully complete 
the request. This function does not return a value. 



FreeRexxPort 

The 1-rceRexxI'orl lunclion provides a clean exit lor your 
ARexx interface Once you have executed tlu-S-tRexxPort function it 

Is absolutely necessary to execute this function when your program 
is done. This functions takes a lot of work off your hands: it replies to 
any messages remaining in your queue, it closes, your ARexx m 
port, it trees any resources it used, ,m^\ it closes the ARexx system 
library. It any of the messages you sent have not returned yet, this 
function will not return until every one ol them is accounted for. 

Communication Routines 

Pie next three library (unctions handle communications 
with ARexx I wo ol these functions are high level functions; one 
synchronous and ovw.' asynchronous. You pass (ewer argument- to 
the higher level functions; therefore, the\ are easier t" use. You will 
most likely get the most use out of the higher level functions. The one 
km level (unction is used when you need the maximum control of 

the communication process thai b possible with the library. You pass 

twice as many arguments to the lower-level (unction as compared to 
the higher level (unctions The main attraction of the lower-level 
communication (unction is lhat vou have a chance to manipulate ihe 
RexxMsg structure before it is sent, and you gel the first look at it 
when it returns. The document file thai is included with the library 
alludes to the tact lhat this (unction is both synchronous and asyn- 
chronous. During my testing, 1 was unable to get it to function 
synchronously. I am continuing to try to work this problem, because 
there are definitely times when you want to wait (or your request to 
Brush executing before you continue with your processing. 

SyncRexxCmd and A SyncRexxCmd 

SyncRexxC md and ASyncRexxCmd are the higher level 
functions (or synchronous anil asynchronous communications re- 
spectively. Other than the bask difference between synchronous and 
asynchronous communications, these lunctions are very similar. Ihe 
SyncRexxCmd function requires three arguments: a pointer to the 
command siring, a pointer to the message structure thai caused the 
act ion. and a pointer to your RexxData structure. The ASyncRexxCmd 
function requires unlv t he command string pointer and the pointer lo 
your RexxData Structure as arguments Both lunctions return a 
pointer to the message Structure it created to communicate with 

ARexx. However, it either funcuort cannol successfully Fulfill your 

request, 11 returns a zero value, and it places a pointer to a null- 
Urmmaled error message in the global variable RexxHrrMsg. An- 
other difference in operation is that the SyncRexxCmd function 
replies to the message that you passed the pointer lor. lliese (unctions 
are main I \ pro\ uledforeaseof use rather than the maximumamount 
of control of the communication process. 

SendRexxCmd 

The SendRexxCmd function, as ihe lowest-level communi- 
cation function of the library, gives you the most control over the 
communication process. Unlike the previous two functions where 
the most control you had was to send a command string, with the 
SendRexxCmd function, you provide the value for the mw\ction 
field of ihe message structure, a pointer to a message Initialization 
function, a pointer to a command string, a pointer to a returned 
message (unction, a pointer to the message that caused this action, 
and a pointer to your RexxData structure listing One contains the 
prototype for the SendRexxCmd function The most promising pos- 
sibilities come irom the two function pointers you provide. 
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You can use Ihe first function to modify or initialize any 
fi«ld In the message structure before ills sent out. IheSendRexxCmd 
function performs a default initialization before passing the message 
structure lo your routine. Of particular interest to us are the ARG1- 
ARG13. mi Passport. rm_CommAddr, Stdin and Stdout fields. 

The SendRexxCmd function initializes the ARGO field with 
the pointer to the command string you passed as voui third argument 
in the function call, and it uses ARG14 and ARG15 for its own 
purposes. This leaves you the ARG1-ARG13 fields to use however 
you see tit You can use these fields to pass additional argstrings, C 
style terminated strings, numeric values, or am other value that you 
can fit into a STRPTR (long) data type. However, von .in responsible 
to free any memory allocated to pass argstrings or C style null 
terminated strings. You can free this memory in your error and result 
routines described earlier or in the returned message function for 
which you pass a pointer to the SendRexxCmd function It is impor- 
tant to remember that if you use some of the ARC1-ARG13 fields to 
pass values other than argstrings, the program that receives the 
message must be prepared to process those values- This eliminates 
ARexx macros because they expect argstrings only. 

The rm_PassPort field holds, i message port address. AKexx 
will parse the ARGO value to extract the command name. ARexx will 
then search for a program by that name. If the program is not found. 
ARexx will pass the message to the message port address in the 
rm_PassPort field. The command name in ARGO mav not be a 
program name at all but a command that the other program, whose 
message port address you put in rmJPassPort, recognizes. This 
provides a convenient way for you to pass commands to another 
program using the ARexx resident process as an intermediary. I* this 
field is a NULL and ARexx can not find the program, then ARexx 
returns the message with a "Program not found" error message 

The rm_CommAddr field on the other hand provides awa\ 
lo override the default initial hostaddres- | hja is I null-terminaled 
stringandis"ROXX" by default. The ARexx l_ ser's Reference Manual 
states, "The host address is the name of the message port to which 
commands will be directed ...." You can redirect that command 
message traffic by supplying your rn.-ss.ige port name as the default 
address Ihe macros vou run with vour message DCK1 name Bfl the 
default host address no longer need to execute the ARexx address 
instruction to direct commands to your program. They come to vour 
program automatically now. This is convenient if your program 
supports multiple instances of itself. Each instance of your program 
will have a unique message port name. This message port name will 
be used as the default host .uldressbv each instance. That allows each 
instance of your program to run exactly the same macros, and Ihe 
commands issued by those macros will In- routed automatically to the 
correct instance of your program by use of the default host address 
value. Still a little vague? I will try to clarify it further with an 
example. 
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That macil) is easy enough to understand. First it prints a 
message alerting the user that it is running, sends .i save command 
and then quits Without the ARexx address command, the SSVC 
command is sent directly to the ARexx resident prinress because the 
default host address is "RFXX". If this macro is executed with your 
host address name supplied as the default, Ihe save command would 
be sent directly to your program. With multiple instances of your 



program running, each with unique host address names, the save 
command will be sent to the proper instance of your program by use 
otthedefault host address name when they execute this macro. Using 
this feature allows you to write macros that can be used by any 
program that supplies the proper default host address, and multiple 
programs ,,m execute these macros, simultaneously. 

The last two fields of interest, rm_Stdin and rm_Stdout, 
allow you to redirect the input and output streams. If your program, 
for one reason or another, has no default input and output streams, 
it will be necessary for you to supply values for these fields if your 
macro prints any information to the screen or prompts the user for 
any information 

The second function you supply to the SendRexxCmd 
Function gets the tirst look at the message structure when it returns 
You can use this routine to extra. I any special values you expect to be 

retumed< Vou may also need to free some memory used by argstrings 

vou sent. This function can also be called after a fatal error, so it is 
important to test return values before using them to ensure that they 
are -ate to use I his function is passed a pointer to the RexxMsg you 
sent out, therm_Resulll value and the rm_Result2 value. The docu- 
ment tile that comes with the library says that if no routine is supplied 
then the SendRexxCmd function executes asynchronously. There- 
ton'. I assume that if a routine issupplied, the SendRexxCmd function 
executes synchronously. However, even when I supplied a routine, 
IheSendRexxCmd function continued to execute asynchronously. I 
am continuing to lest this function. 

Conclusion 

Well, that is a fairly detailed description of the the 
rexxapp. library written by Jeff Glatt of Dissidents Software. The 
program included with this article is a completely functioning pro- 
gram with just a shell of an ARexx interlace In Part Two of this article 
we will complete the interface. As the program is, it is completely 
useless except as a good test bed to explore the operation of the 
rexxapp. library. If you are ingenious, you can modify it a little to lest 
every function in the library. 1 have done that myself. The completed 
program will be a program that you can get some use out of 

If you examine the source code in Listing Two, you will get 
abetter ideaofsomeofthematen.it I presented in my description of 
the rexxapp.ltbrary. Because it is just an interface shell rather than a 
fully functioning interface, the RexxData structure includes only the 
commands available in the program's project menu. 

\\ hen we complete Ihe interlace, we will give it access to 
more commands, some of which are available only through the 
ARexx interface. For some of the commands, we can write ARexx 
macros lo execute them to reduce the size of Ihe memory-resident 
host application I encourage you to take a close look at Ihe program 
to see what potential it has for you. This program is intended lo be 
running in the background at all limes for quick access to information 
stored in small database type files You access it through the Alt-Ctrl- 
f key combination, pull up Ihe information that your are looking for, 
and then put the program back to sleep until you need it again. All it 
needs t" reach this goal is more file access commands and some 
display commands so \ ou •.-*'* see what is in the files. This is what we 
will be adding in the next part of the article. If you think you could get 
some use from a program like this, \ on can send me suggestions and 
ideas tor commands you would like to see included in it. You can 
le.u <• me a mes-age on C.lnie using the e-mail address, D.BIackwelll. 
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For more information on advanced ARexx topics, see: 

An Introduction to IPC with ARexx by Dan Sugatski (ACs TECH Volume I, Number 1) 

Interfacing Assembly Language Applications to ARexx bx JeffGlait (ACs TECH Volume 1, Number 2) 

Intuition and Graphics in ARexx Scripts bx Jeff Clan (ACs TECH Volume I . Number 2) 

C Macros for ARexx? by David Blackwel'l {ACs TECH Volume 1 . Number 3) 

GPIO-Low-Cost Sequence Control by Ken Hall (ACs TECH Volume I , Number 4) 

Programming with the ARexxDB RecordsManager bx Benton Jackson [ACs TECH Volume 1 , Number 4) 

STOX— An ARexx-based System for Maintaining Stock Prices by Jack Fax {ACs TECH Volume 1 . Number 4) 

Back Issues available while supplies last! Call NOW! 1-800-345-3360 



AC'S TECH^ 



The Amiga and the 
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Hardware 




CAUTION: Be careful when attempting tobuild and conned liard ware 
projects to your computer. Always check you work twice before attach- 
ing the project to your computer. Attaching a home-built project to your 
computer may void your warranty. PiM Publications, Inc, its agents, or 
the author, is not responsible for any resulting damages, from the use or 
misuse of this project. As alttiii/s. use common sense. 

A revolution began in 1983 when several electronic musical 
instrument manufacturers joined to publish a standard describ- 
ing a system of communication between music synthesizers. The 
Musical Instrument Digital Interface or MIDI is now available on 
almost all electronic musical instruments. MIDI allowssynthesiz- 
er>, sequent ers, rhythm machines, and effects boxes to control 
one another and has greatly expanded the role computers now 
play in music. With right software, an Amiga connected to a M IDI 
instrument can record and play back a performance, edil and 
print a musical score, act as a synthesizer patch editor and 
librarian, and even teach you how to play! 

MIDI is a digital serial communication specification that 
consists of a physical standard which describes the type of 
connector and cable to interconnect MIDI devices, a hardware 
standard that specifies the design of the electrical interface and a 
software standard which establishes the typeand format of MIDI 
messages. MIDI has become such an important communication 
system that some models of the Macintosh and Atari have MIDI 
ports built-in. 

While this is not intended to be a do-it-yourself construction 
guide to build ing a MIDI interface, with some degree of technical 
skill and the information in this article, you'll find it quite easy to 
put one together. Be aware that you bear complete responsiblity 
for any damage caused by the design and construction of such an 
interface based on information presented in thisarticte. Unlike an 
annoying program bug, an error in your design could cause 
severe damage to your computer and any connected MIDI de- 
vice Repair technicians are notably unsympathetic about hard- 
ware hackers' mistakes and are apt to charge accordingly. It goes 
without saying that the addition of any home brew circuit effec- 
tively voids the manufacturer's warranty. Proceed cautiously! 



by James Cook 
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Learn the ins and outs of the mysterious MIDI Hardware Specification... 
and build your own MIDI Interface! 



The Physical Specification 

The typical MIDI compatible di*vu e usual!) has three 5-pin 
female DIN ports. The MIDI l\ port receives transmissions ftom 
other devices, the MIDI OUT port transmits data to other devices 
and the MIDI THRU port acts ,t--,i MIDI OUT for all data meiwJ 
at the MIDI IN port. Each MIDI OUT port can supply oneandonlv 
one MIDI IN port. For this reason some MIDI devices ha\e several 
MIDI OUT ports to transmit signals to multiple MIDI instru- 
ments. A MIDI cable consists of a shielded single twisted pair of 
n ires with male DIN plugs on each end. The shield of the cable is 
connected to pin 2 and the twisted pair is connected to pins -1 and 
5. Pins 1 and 3 are not defined and the specification recommends 
they not be used. The cable may not be longer than 50 feet. Note 
that the 5-pin DIN cables sold to interconnect some types of hi-fi 
equipment are not MIDI cables. Hi-fi DIN cables do not have the 
shield connected to pin 2 and therefore these cables are more 
susceptible to induced electrical noise interfering with the MIDI 
signal. 

The Software Specification 

While this article is primarily a discussion of the MIDI 
hardware standard, some mention of the sott ware specification is 
needed. A complete treatment ot MIDI software programming, 
however, would require several articles Briefly, most MIDI 
communications consist of multi-byte messages which are con- 
structed of one Status byte followed by one or two I )ata b\ tes 
Messages are divided into two types, Channel and System. 
Channel messages include a four-bit number in the least signifi- 
cant nibble of the Status byte to indicate which one of 16 MIDI 
devices is to respond to the message. The most significant nibble 
signals the receiver as to the function the transmitter expects it to 
perform. The most significant bit in the Status byte is always set 
to differentiate Status bytes from Data bytes. Two exceptions to 
this message format are System Real-Time and System Exclusive 
messages. Real-Time messages are used for synchronizing all 
MIDI devices in the system including sequencers and rhythm 
units. Exclusive messages are special communications whichany 
manufacturer may define for use between its own MIDI devices. 



For example, to send a message to MIDI device 7 to play 
middle C mezzo-piano, the transmitter would send 1O01O100 
0011 1 10001000000. 1001 = NoteOn,0100 = channel 7,001 II 100 = 
Ml (middle C is note number 60), 01000000 = 64 (a note velot. ity 
roughly equal to striking a piano ke\ me/zo-piano). Note that 
this message simply commands device seven to begin playing 
middle C. Middle C will continue playing until it is commanded 
to stop with a Note Off message or a Note On message with zero 
velocity. Another important message is the Program Change 
message which commands a receiving device to select a new 
voice 

or patch setting. There are several other messages as well includ- 
ing control signals from pitch wheels, breath controllers, etc. 
MIDI software has greatly expanded from that defined in the 
original specification. The members of the International MIDI 
Association recognized that this was inevitable and desirable and 
actively encourages member manufacturers to make readily 
available information on new commands or message formats that 
a firm may introduce on new equipment. 

The Hardware Specification 

The MIDI signal itself is a 5 mA current loop operating at a 
speed of 31.25 Kbaud (+/- 1%), asynchronous. Each byte is 
transmitted by a Universal Asynchronous Receiver/ 'Transmitter 
or UART integrated circuit and is preceded by a start bit and 
followed by a stop bit. While the transmitter design is relatively 
noncntical as long as the 5 mA current loop ition is 

adhered to, the receiver circuit must contain an optoisolator 
which has a rise and fall time less than two microseconds. The 
main purpose of the optoisolator is to ensure that the transmitting 
MIDI de\ ice is electrically isolated from the MIDI receiver An 
optoisolator with as fas! a rise and fall time as possible helps 
reduce the dreaded "MIDI delay" problem which occurs when 
I luming more than three or four instruments MIDI delay will 
cause the farther instruments to play noticeably after a key is 
pressed on the transmitting instrument. 

The MIDI specification identifies two optoisolators. the 
Sharp PC-900 and the 1 1 1" 6N 1 W, as acceptable although others 
nt.n be satisfactory. The hardware specification includes a sche- 
matic diagram of the final receiver, transmitter and thru portions 
of a MIDI interlace. Sec' Figure 1, 
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Figure One 



TheMIDl OUT port haspin4 of the female 
DIN jack connected to +5 volts through a 220 
ohm resistor. Pin 5 is the transmitted signal 
which also passes through a 220 ohm resistor. 
One or more invcrtors, as shown in Figure 2, art' 
used to buffer the output of the L'ART and to 
ensure that current is ON for a logical 0. The 
MIDI IN port receives the signal at pin 4 which 
is passed to the input of an optoisolator through 
v.-i another 220 ohm resistor. Inside the 
optoisolator is an LED which turns on and off 
with the received signal. The to 5 volt signal 
transmitted from the U ART divided by the total 
resistance of the three 220 ohm resistors and the 
LED makes up the 5 mA signal. The light emit- 
ted by the LED inside the optoisolator falls upon 
a photoreceiver which switches a +5 volt signal 
on and off. This signal is passed on to the receive 
section of a serial UARTandisalso buffered and 
connected to the MIDI THRU port, il present, in 
the same way as a MIDI OUT port. Pin 2 is left 
unconnected at the MIDI IN port to prevent 
shield ground loops which could induce electri- 
cal interference into the MIDI signal. 
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Figure Two 



The Amiga Interface 

Unlike Apple and Atari, Commodore did 
not design a MIDI port into the Amiga, choos- 
ing to rely on third party developers to provide 
I suitable interface. Fortunately, the Amiga en- 
gineers did provide a programmable UART 
integrated circuit for serial communications 
capable of being set tocommunicate at the 31.25 
Kbaud speed required by MIDI. Unlike most of 
the serial ports available for PC clones, this 
allows the Amiga to send and receive serial 
communications at the rather speedy rate de- 
manded by MIDI standards without the addi- 
tion of a suitable UART in the MIDI interface. 

The only thing an Amiga MIDI interface 
must provide in addition to the standard MIDI 
circuit is the hardware to properly implement 
the 5 mA current loop output and the to 5 volt 
input from the optoisolator. Since the Amiga's 
serial port is a standard RS-232 port normally 
used to communicate with modems and serial 
printers, it is designed to send and receive sig- 
nals which switch between -12 and >12 volts. 
Some form of signal level conversion is neces- 
sary to convert the + /- 12 volt signal to to +5 
volts. The two most common level conversion 
chips are the 1488 and 1489. The 1489 accepts 
almost any voltage level input and converts it to 
to +5 volts. The 1488 performs the opposite 
function, converting a to +5 volt signal to ,\ 
signal which switches between voltage levels 
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applied at pins I and 14. These two chips are also u>ed inside the 
Amiga itself to convert the to *5 volt signals generated by the 
internal logic to drive the RS-232 port. See Figure 2. 

Toconvert a received MIDI signal, one must feed the output 
of the optoisolator directly to pin 2 of a 1488. With the exception 
of the Amiga 1000, all Amiga serial ports have *12 volts con- 
nected to pin 9 and -12 volts connected to pin 10 of the DB-25 



Vol. 2, Num. 1 ©1991 



connector. The 1488 can be powered by connecting pin 9 of the 
DB-25 connector to pin 14 of the 1C and connecting pin 10 of the 
serial connector to pin 1 of the chip. Pin 7 (Ground) should be 
connected to pin 7 of the DB-25 connector. Pin 3 of the 1488 will 
provide a + /- 1 2 volt signal to the receive input, pin 3, of the serial 
port. While the 1488 contains four converting gates, only one is 
needed. Amiga 1000 owners will find this method of signal 
conversion difficult to implement since the 1000 does not supply 
-12 volts through the serial connector (+12 volts is available from 
pin 23). Amiga 1000 users will either have to supply -12 volts 
externally or use an integrated circuit like the Sipex Sl'232 which 
contains a voltage doubler and invertor circuit to convert *5 volts 
to a +/- 10 volt signal level, which will be adequate to drive the 
RS-232 port. 

Thetransmitted signal from pin 2 of the Amiga's serial port 
must be converted from +/- 12 volts tea to +5 volt signal. Since 
only the Amiga 1000 provides a +5 volt power output from its DB- 
25 connector (pin 21), a 7805 +5 volt regulator should be used. 
Power from pin 9 of the DB-25 connector is applied to pin I of the 
7805 and ground from pin 7of theconnector is wired to pin 3. The 
+5 volt output from pin 2 of the regulator is connected to pin 14 
of the 1489 IC. The 1489, like the 1488, also provides four gates. 
This allows the use of one 1489 to supply three MIDI OUT ports 
and one MIDI THRU port. Connect pin 2 of the Amiga to pins 1. 
4, and 10 of the 1489 and you'll have MIDI OUT's on pins 3, 6 and 
8. Simply connect pin 3 of the 1488 to pin 13 of the 1489 and pin 
11 will providea MIDI THRU output. Since theSipexSP232chip 
contains two RS-232 to digital receivers and two digital to RS-232 
transmitters, you may want to consider using it if you need a onlv 
single MIDI 'OUT, a MIDI THRU and a MIDI IN port. The 
advantage to using thischip is that you could providean external 
source of +5 volts to power the circuit, and the interface could be 
connected to any Amiga computer (with a gender changer (or the 
1000, of course). Small wall socket power supplies of »? volts are 
readily available and relatively inexpensive. 

Construction Hints 

Construction of an Amiga MIDI interface can be quite simple. 
Assembly techniques are non-critical and most of the electronic 
components required are available at your local Radio Shack or 
other electronic parts outlet. Only the optoisolator or the Sipex 
chip will have to be special ordered. Total cost will he around $30. 
I lere area few tips which can be applied to any hardware 
you intend to connect to your computer to reduce the chance of 
accidentally damaging your machine. All designs should be 
sketched and thoroughly researched beforcanythingisassembled. 
Your initial circuit should be built on a solderless breadboard 
which allows quick and easy changes. After double checking 
your breadboarded circuit for accuracy, connect vour circuit to 
the Amiga in the safest way possible. Since the Amiga's power 
supplies are reasonably well protected against shorts or over- 
loads, simply powering up (he circuit should be your first step 
For the MIDI interface, for example, connect only the */- 12 volt 
pinsand ground to your prototype circuit from the computer with 
the power off. With a voltmeter connected to ground and +12 volts, 
switch on the computer. If the voltage does not immediatclv rise 



to around fl2 volts, wrifefi iputer, Disconnect the inter- 

face and switch the computer on again. L heck between pin 7 
(ground (ami pin 9 (+12 volts) on the RS-232 connector to make 
sure vou haven't damaged the +12 volt supply. If you are power- 
ing > our interface through the serial port of your computer, make 
sureyouhavea serial cable with all 25 pins connected. Most serial 
cables have only the most commonly used pins connected. It von 
are trying to use one ol these cables, the* /-1 2 volt line? will not 
be connected to vour interface and the circuit will not work. Be 
careful using a serial cable with all 25 pins connected with any 
other serial de\ ke. Some modems, serial printers, etc., may be 
damaged by the presence ol these 12 volt signals 

Once you've established that the circuit is not shorting or 
overloading the +/-12 volt supplies, connect the transmit and 
rei ei\ e pins to the interlace and again measure the voltage after 
switching on the computer. If everything seems to be working 
properly, switch off the computer and plug in a MIDI cable 
between the MIDI OUT port and MIDI IN port of your inleit.ue 
Check vour voltage lev els once again. \ow b(H)t up your machine 
and run your favorite telecommunications or terminal program. 
It doesn't realb matter what baud rateoi bit set tings a tensed, but 
make sure your local echo is turned off. Now, type on the 
computer keyboard. It everything is working properly the tele- 
communication or terminal program will be sending the charac- 
ters you type out the serial port and into your interface. The 
interface will transmit the characters using the MIDI signal 
standard from the MIDI OL I port and 

receive the same characters back on the MIDI IN port The 
interface will convert the received Mgnals back to the RS-232 
standard and the typed characters will be echoed on the screen. 
|ust to make sure you've sot your communications program up 
right, disconnect the MIDI cable and the characters should no 
longer be echoed to the screen 

isiiig the Interface 

You're now ready to give the interface a try' This interface will 
work with almost all MIDI software available for the Amiga. It 
has been tested with DWm.vc AIhsu Construction Si7, ffcirs ct Pipes, 
Tiger Cub and several publk domain programs. Plug a MIDI cable 
from the MIDI OUT port of your interlace to the MIDI IN port of 
any MIDI compatible keyboard. Use another MIDI cable to 
connect between the MIDI OUT port of the keyboard to the \1 II )l 
IN of your computer. The only time you'll need the MIDI THRU 
port is when you want another MIDI device to receive the same- 
signals received bv the computer. 

Follow the instructions on accessing a MIDI device care- 
fully when running a MIDI program. Deluxe Music Construction 
Set. tor example, requires you to explicitly enable the MIDI input 
and output features from the menu You also have to declare a 
MIDI channel and 'program change' or voice setting in your 
score W hile DM( S is capable of providing an excellent means ot 
directly editing a score into a format to drive MIDI devices, it does 
not have the performance input features of a sequencer program 
like Bars & Pipes, Music- X or Tiger Cub. If your MIDI keyboard 
is a synthesi/er, you ma) wish to look into the many patch 
librarians available to help organize and store your settings. 
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Programming the Amiga in Assembly Language 

Part I— Getting Started 
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ISTRODUCTION 

Writing assembly language programs for the Amiga is not 
that complicated. The commands arc short, simple, and varied 
enough to lei you do two or three routines with just one phrase 
I have placed a glossary of commands at the end of this article, 
and also 1 will discuss each one when it's used. In this series I'll 
cover several types of programming techniquesand demonstrate 
a new procedure in each article. All of the machine language 
programs may be assembled using the A68K Assembler and 
Blink, both excellent public domain programs, included on this 
disk, no other files or "includes" arc necessary. You will need to 
refer to previous articles as we go along since not much old 
information will be repeated. All of the programs will run on an 
Amiga 500 using WorkBench vl.2 or higher. Thanks to Adrian 
Kotik for debugging, proof-reading, and putting these articles 
together. 

First, let's get some terminology out of the way. Your 
computer is filled with memory locations called bytes. Each byte 
holds eight bits (called, from leftto right, bit7 to bit0> of informa- 
tion either a "0" or a "1." Using just these two numbers (called 
binary or Base 2 system) all values, commands, and instructions 
can be represented. In one byte alone, there are 256 (2*) possible 
combinations of "0" and "1." If you combine two bytes you get 
one "word," and two words make up one "long word" that holds 
32 bits of information. With only 512,000 bytes available in a 
Standard Amiga 500 with no additional memory, you can begin 
to get some idea of how much storage room is available. 

Even though the computer uses the Base 2 for its numbers, 
programmers find it easier to use the decimal Base 10 or the 
hexadecimal Base 16. With the latter, you have to add six addi- 
tional numbers (called "A" through "F") to the usual 1 through**. 
So 10 in the Base 16 is 9*1 or A, 1 1 is B, and so forth; 16 l0 is 10 u . 
Since the largest number a byte can hold is 255 10 , it is often 
convenient to think of that as FF 1(1 . To distinguish numbers in the 
Base 16— usually called HEX— from numbers in the Base 10, the 
HEX numbers are prefixed with #S and HEX locations In the 
computer's memory are prefixed with S. 

REVIEWING THE BASES 

If you're familiar with Base 2 math, you might want to skip 
this section. With just two numbers to use, the binary system isn't 
that complicated but this is a good time to review it Addition i> 
simple; 0* 1 = 1 and 1+1=10. Since each digit represents a power of 



two. the number 1 1 1. would represent ( 1 '22)»( l'21)+( l"20)or7 (0 . 
As numbers get higher, they also get longer to write so you can see 
why the Base 16 or II IX became popular. Now with each number 
representing a power of 16, the number #SFF would mean 
(F'161)+(F*160) or 255 - remember that A through F in HEX 
actually represent 10 through 15 in Base 10. 

The most confusing part of computer math is probably 
negative numbers. Since there is room for only those O's and 1 's, 
how do we get a minus sign in there? You have to think of the 
numbers you're using as being on a giant wheel going from to, 
let's say, ffSFFFF. This number fills all the bits of one word so it 
makesaconvenientexample.Tumingourirnaginarv wheel to the 
left will show all the positive numbers: 0,1,2, etc. Rotating in the 
opposite direction must then indicate the negative numbers. 
Since the first negative number is KSFFFF, it must be the same as 
• 1 ; next would be CSFFFE and it must be -2 and so forth. Halfway 
through the wheel in either direction is the boundary between 
positive and negative numbers. 

The only difference between our positive and negative 
numbers is that the left-most bit (or Most Significant Bit) of any- 
negative number must always be set, that is, be a " 1 "; the MSB of 
any positive number must always be a "0." This will be true for 
whatever size number you use— byte, word, or long word. Since 
we said that half-way through the wheel was the change-over 
between plus and minus, we can effectively use only half of our 
number range if we are going to need negative values. That is, if 
your numbers range from to «*SFF, the portion from to #S7F is 
positive and from *$FF to "$80 is negative. So the smallest 
number is -128 and the largest is +127. If you need numbers 
outside these values you'll have to increase the size of the range, 
probably from one byte to one word or "SFFFF. Now the numbers 
from to »S7FFF are positive and from #$FFFF to #58000 are 
negative. 

I said that this was necessary if you wanted to use negative 
numbers. But what if all your values will be positive ("0" is 
always considered positive)? No problem; use the full range of all 
your numbers, that is, from to #$FF (0 to 255) or from to 
ffSFFFF. The computer will work the same, but is it up to you to 
interpret the results. 

When we get to BRANCH commands later on, you'll see 
that some of the branches will depend on whether you could have 
a negative or positive result. More mistakes are probably made in 
this ansa than anywhere else. Your program can go along per- 
fectly and then suddenly display the "Big Bang'' theory simply 
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ix cause you forgo i ih.it i here could be negative vahiesand didn't 

branch accordingly. My early examples will all use positive 
values so we won't have to worry about negative branching yet. 
And what about fractional numbers? That's even more fun! 

SETTING UP YOUR ASSEMBLER DISK 

Enough theory. Let's actually get set up and try a simple 
program. 1 suggest you usea stripped down version of WorkBench 
adding A68K and Blink which are both included on this disk. 
There may be later versions of those two PD programs, but I've 
had no problems using, these. You can create your own disk bv 
copying a WorkBenchdisk and removing the unnecessary files or 
start with a blank disk, format it, use INSTALL to make it self- 
bootingand then add these files. Name thisdisk ASSEMBLER:. I 
find it easier to put the programs and commands I'll be using in 
RAM: and RAM:C so my disk and start-up sequence look like: 



tECTORY OF ASSEMBLER 



C DIRECTORY 


I DIRECTORY 


DEVS DIRECTORY 


a68K 


Port-Handte 


narrator device 


Mr* 


Ram-HanJef 


pwiidufci 


cd 




printer device 




copy 


S DIRECTORY 


sySefn-configuratiori 


MM 


startup-sequence 


PRINTERS DIRECTORY 


* 




(your printer) 




■d 


UBS DIRECTORY 
matrtoeedoufatesKnry 




■fed) 


FONTS DIRECTORY 


m 


mathttans horary 


lopw.tont 


more 


wnsiatorJCrary 


TOPAZ DIRECTORY 
11 



There may be other C commands you want to add such as "type" 
or "info" but they probably won't be needed in RAM:C. Now that 
you have the necessary files on your ASSEMBLER disk, I suggest 
that you use the following start up -sequence. 



ASSEMBLER;S/STARTUP-SEQUENCE 



dir ram; 

makedir ram:c 

copy c/a68klblmklcd!copy ram:c 

copy c/deleteldirledfmakedir ramc 

copy c/more ramx 

path ramc 

cd ram: 



This startup-sequence will copy all of the files you will be 
using into RAM:C and will put you in the root directory of RAM: 
where you'll be saving and assembling your programs. At this 
point I suggest formatting a fresh disk and calling it PROGRAMS. 
Once the programs have been debugged and assembled in R A M : , 
the executable programs and source codes will be copied onto 
this disk. While all of the libraries on your ASSEMBLER disk 
won't be used immediately, you might as well start tracking them 
down now. They'll all be needed eventually. 



I use ED to type the programs, but you may use any word 
processor that saves files in the ASCII mode. When writing a 
machine language program the routine heading goes immedi- 
ately to the left; commands must be at least one space over but I 
use one tab over; the rest of the line, if any, must be at least one 
space or tab over from the command. Comments may be added 
but must be preceded by a semi-colon. It is always a good idea to 
add as may comments as possible; two months after you write a 
program it will be hard to remember what all those lines were 
supposed to do. And try to make routine headings a good 
understandable name. It's easier to figure out what 
"SendToPrinter" will do rather than "L10". 

YOUR FIRST ASSEMBLY LANGUAGE PROGRAM 

This is a short, simple program that will get you started and 
let you check out your new disk. It causes the red power light on 
your Amiga to blink off and on six times. Right now don't worry 
about the commands and all those other cryptic symbols (we'll 
get to them later); |ust type it in as written. Boot up your Amiga 
with the ASSEMBLER disk and type in the following program 
using ED or your favorite word processing program. Since ma- 
chine language programs use simple words and phrases I prefer 
using ED. It's also a fairly short program itself and takes up very 
little room in RAM:C. 



start : 






move. 1 


sp, stack 


.-save the Stack Pointer 


number_of_ 


■ 




moveq 


16, dl 


.-number of times to blink 


power_of f : 






or.b 


•2,$bfeOQl 


;set bit one to 1 


moveq 


• O.dO 


; clear dO 


delayl : 






subq.w 


11, dO 


; subtract 1 from dO 


bne.s 


delayl 


,-branch if not back to 


delay2: 






subq.w 


11, dO 




bne.s 


del ay 2 




power_on: 






andl . b 


•253.$bfc001 


.-clear bit one to 


moveq 


• O.dO 




delay 3: 






subq.w 


11. dO 




bne . 


del ay 3 




delay4: 






subq.w 


• l.dO 




bne.s 


delay* 




subq 


11, dl 


.'decrease number of blinks 


bne.s 


power_of f 


.-branch if not finished 


move. 1 


stack. sp 


; restore the Stack Pointer 


rts 




.•return to CLI 


even 




; force an even address 


stack del 





.-stack storage 


end 




;end of listing 



After typing this program, save the source code in RAM: as 
POWER.ASM; all A68K programs must end with .ASM. To 
assemble it, type A68K POWER.ASM. Since you're in RAM:, the 
disk won't have to come on and the assembly is extremely fast. If 
there are any mistakes, the assembly listing will stop and tell you 
what line has an error. If you were lucky enough not have to have 
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any errors the first lime, try changing the first "move I" to read 
"mave.l". Now when you assemble, you'll get an error in line "2 
and the phrase "No Such Op-Code." Generally the A68K assem- 
bler will only catch syntax errors and some type mismatches 
(bytes, words, etc). The assembler can't tell you if your program 
won't work properly or may crash 

After assembling a program. AfvSK . reates a new fiU — in 
thiscasecalled POWER.O. ThisObject file must be linked to make 
it an executable program, so type BLINK POWER.O. Now you 
have another listing called POWER; this is the assembled pro- 
gram. At some later time you may want todelote the accumulated 
.O files. Before trying the assembled program, I would save it 
along with the source code to disk; if your program does crash, 
you'll loose everything in RAM;. You can either save your pro- 
grams to the assembly disk or, as I usually do, to a Second 
program-onlv disk called PROGRAMS. From RAM; type COPY 
POWER.ASM PROGRAMS: and COPY POWER PROGRAMS:. 
As you get more programs, you may want tocreatedirectories on 
your program disk and save programs in them, but for the time 
being you can save this short program directly to disk. 

Now you're ready to try your program. Type POWER and 
the Amiga red light should blink six times and then stay on. 
Congratulations! For many of you that was probably your first 
assembly language program. By the way, throughout this series 
I use "assembly language" and "machine language" interchange- 
ably. With your first program out of the way, it's time to get down 
to basics and discuss how the Amiga processes the machine 
language programs. 

GETTING TECHNICAL 

The Amiga stores information in registers There are eight 
32-bit registers used for data (dO to d7) and seven used for 
addresses (aO to a6); an eighth register <a7) is available but it is 
generally used as a Stack Pointer (SP) for saving information 
locations. Part of yet another register (CC) tells you the "Condi- 
tion Code" for any operation — mainly if an operation produced 
a value of or not, and if the result was a plus or minus number. 
There are four main points to remember when writing Amiga 
machine language programs: 

1. All main headings (library, array locations, etc.) will be at 
different locations when you first power-up; well, all but one. 
This forces you t<» write "locatahle" programs but more about 
that in a later article. 

2. Most subroutines are located in various libraries and are 
accessed by going to an "offset" location from the library-. 

3. Important items are structured; when setting up a screen, for 
example, there are various elements that must be defined in 
a specific order. This allows you to change parameters since 
they are at a fixed distance from the main item. 

4. All address locations must be even addresses — this is usual I v 
handled by the assembler. 

Finally, a brief discussion of the two major commands used 
in assembly language. MOVE is used to put a value or the 
contents ot one register intoanother register. Some of the possible 
variations on MOVE are: 



MOVE.B moves the right-most byte 

MOVE.W moves the right-most word 

MOVE.L moves the entire long word 

MOVEA moves only to an address register 

MOVEQ moves a signed byte value (a number Irom 

-128 to *127) to a data register 

MOVEM moves several registers at once 

The other command is LEA — Load Effective Address. It's used to 
move labeled locations to an address register or to increase the 
contents of an address register. Some examples are: 

LEA name.al moves the location or address of "name" into a 1 
LEA I00(at) increases the address in al by 100 

Any command with a parenthesis around a register means "the 
contents of." 

HOW WE DID THAT? 

With that general information, let's review how you caused 
the power light to blink several times. The MOVE.L command 
saves the contents of the Stack Pointer in a location called "stack " 
Next, a MOVEQ was used to store »6 in register d 1 . In the Amiga 
500, location SBFE001 controls, among other things, the power 
light, libit 1, the second bit from the right is "0" so the light stays 
on, but if that bit is set to 1, the light will go out The Basic AND 
and OR commands have the same meaning in assembly language 
and are often used to force a bit location to or 1. Any binary 
numberORI willalwaysbe 1 while any numberORO remains the 
same; any binary number AND will always be and any 
number AND 1 remains the same. So when you OR a byte with 
•2 (10,) bit 1 is set to 1. 

Next, register dO is cleared with a MOVEQ #0 command — 
bv the wav. this is thequickestwavtoclear any data register Then 
*1 isSUBtracted fromdO(resultin'gin#$FFFF);SUBQand ADDQ 
may only be used with values between «1 and "8. The BNE 
(Branch if Not Equal to 0) will go back to "delay 1 :" until dO finally 
reachesO; theS indicates a Short branch (-1 28 to + 127 bytes away). 
Then the entire delay is repeated so you can notice it. The light is 
turned back on by clearing bit 1 with ANDI.B #253 (1 1 1 1 1 101 ,); 
the "I" means that an Immediate number will be used with the 
AND command. After two more delays register dl is decreased 
by 1 and the entire sequence repeated. Whendl finally reachesO, 
the original contents of the Stack Pointer are restored. The RTS 
(ReTum from Subroutine) takes us back to CLL EVEN is a code 
to align the assembler to an even address; as 1 mentioned earlier 
all addresses must begin at an even numbered location. After the 
actual program a space is reserved as "stack" using the storage 
command DC.L (Define Constant as a Long word value of 0). 
FinatK, I \D signifies the end of the listing. 

Let's talk about those libraries in more detail. The major 
ones we'll use in this series are EXEC (tasks, memory, and ports), 
IK)S (disk functions, read, write), GFX (graphics). MAUI. 
MATHTRANS (sign, cosine, etc.), INT (windows and screens), 
and TRANSLATE (speech). While there are several more librar- 
ies, we'll work mainlv with these. All the subroutines we use are 
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A few notes before you dive into the disk! 



You need a working knowledge of the AmigaDOS CLI as most of ihe files on the 
ACS TECH disk arc onlv accessible from the CLI. 



In order to fit as much information as possible on the ACs TECH Disk, we archived 
many of the files, using the freely redistributable archive utility 'lharc' (which is 
provided in the C: directory), lharc a/chive files have the filename extension ,\ih. 

To unarchive a file/iw. /r/i. type lharc xfoo 

For help with lharc. type lharc ? 

Also, files wilh lock ' icons can be unarchived from ihe WorkBench by double-clicking ihe icon, and supplying a path. 




We pride ourselves in the quaflty of our print 
ond magnetic meata pubfceahons However, in 
the highly un-Vety event ot a faulty or dam- 
oged d«sk. pteose return the dtek to PiM 
PutoKconons, inc. for a free replacement 
Please return the dbk to 

ACs TECH 

Dttk Replacement 

P.O. Box 669 

Foil Rrver. MA Q272Q-08cO 



Be Sure to 
Make a 
Backup! 
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located at a specific offset away from its library location. The 
INI I routine is. torexample, MA In tes aw ay trom theGFX library 
location; or, more correctly, 324 bvtes away will tell you to jump 
to some location that actually contains the PSET routine. In 
addition to calling the routines, certain registers must contain 
spcdfk Information for the routine to work. As we use each 
libraryandroutine.nl include the offsets and required infor ma 
tion. 

As I had mentioned earlier, you won't know library ad- 
dresses at power-up except for the EXEC library. It's address is 
always stored in location $4 and it's always available. The routine 
to open another library is called "OpenLibrary" and is located - 
552 bytes away from the EXEC library. For this routine to work. 



feral must contain the location of the library name you want 
to open, and dO must contain the latest acceptable version num- 
ber of that library, usually 0. 

OPENING A UBRARY 

Let's try opening the DOS library . This routine will work for 
all libraries by just changing the library name. The three main 
portions ol this program are the offsets we'll use, the program 
itself, and a data/storage location. After the library is opened, 
we'll use two DOS routines to print a message and print the actual 
library location as a HEX number. The "Output" routine gets the 
CLI screen-handler and returns its location in dO. The "Write" 
routine will print a message or any characters in a string buffer; 



A68K ASSEMBLER COMMANDS 

OPCODES SOURCE. DESTINATION 


OPCODES 


SOURCE.DESTINATlGN 


ADD.BAV/L 
ADDA 
ADDI 
ADDQ 


add a number or register to a register 
destination is address register 
immediate number 


BRANCHES 


GENERAL 


BCC 


Branch it Carry Clear 


BCS 


Branch if Carry Set 


#1 through »8 


BRA 


B Ranch Always 


BCC 


same as Branch il Higher or Same 




BCS 


same as Branch It LOwer 


UNSIGNED: 


BCHG 
BCLR 

BSET 


test a bit and change it 
clear a bit 
set a tut 


BEO 

BH1 

BHS 


Branch it EQual 
Branch it Higher 
Branch if Higher or the Same 


BTST 


test a bn 


BLO 
BLS 


Branch it LOwer 

Branch it Lower or the Same 


CLR 

CMP.BAV/L 
CMPA.W/L 
CMPI 


clear a register 
compare value and register 
compare to address register 
compare immediate value 




BEQ 


SIGNED: 
Branch if EQual 


CMPM 
DIVS 
DIVU 


(address register)*. (address register)' 
signed 16 bit division 
unsigned 16 bit division 


BNE 


Branch it Not Equal 


BGE 


Branch if Greater than or Equal 


BGT 


Branch if Greater Than 


EXG 


swap any registers 


BLE 


Branch if Less than or Equal 


EXT 
EXT.W 


extend the sign 

extend to bits 8 through 1 5 


BLT 
BMI 
BPL 


Branch it Loss Than 
Branch it Minus 
Branch if PLUS 


EXTL 


extend to bits 16 through 31 


JMP 


jump to routine 


BOOLIAN OPERATIONS 

AND BAWL can't use address registers 


JSR 


jump to routine, return when completed 


LEA 

MOVE BAWL 
MOVEQ 
MOVEI 
MOVEA 


Load Effective Address 


move value or register 


must be at least 1 data register 


value is -128 to -127 


ANDl 


immediate value number 


immediate value 


OR.BAV/L 


can't use address register 


move to address register 


must be at least i data reoister 


MULS 
NOP 
SWAP W 


signed 16 bit multiplication 

No Operation 

exchange top and bottom 16 bits in data register 


OR) 

EOR.BArVTL 


immediate value number 
source must be a data register 


EORI 
NEGBAV/L 


immediate value number 
reverse the sign 


TST.BAWL 

SHIFTS -ONL 

shift BAWL 
shift. BAV/L 
ASL 


compare location or register to 




NOT. BAV/L 


reverse O's and 1 s 


f DATA REGISTERS 

• 1 through «7.data register 

data register(»t through *63),data register 

CC<— 


STORAGE 

DS.BAV/L 


define storage (amount) 


DC. BAWL detine constant 

Pointer dc.l 

Title deb my title' .0 

Array del 0,0.0.0.0 
DCB.BAV/L detine buffer (longth. value) 


ASR 


same — > CC 


LSL 

LSR 
ROL 
ROR 


CC<— 

0— >CC 

CC <===> high bit 

bit <===> CC 
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this command requires Ihe handler location from "Output" to be 
in register dl, the message or buffer location in d2 and the length 
of the text to be printed in d3. Any text must be stored in a byte 
storage area (DC.B) and surrounded by single quotes; text is 
usually followed by a comma and to indicate the end of text. 
While "Write" does not check for a 0, the can be used to 
determine text length. Often a ",10" is included after the text to 
force a linefeed or jump to the next line, but be sure to count it as 
a character string and include it in d3. 

Let's look at Listing 1 inmoredetail. Asshortasitis,thiswill 
be the format of most of the programs we'll write — define equates 
and offsets, set-up. the main program, close-out, and data/ 
locations. It's really pretty easy to understand the general proce- 
dure. 

The first two offsets 1 used "OpenLibrary" and 
"CloseLibrary" are both in the EXEC library; after their offset 
values, I have included the information that must go in specific 
registers for the routine to work. The next two offsets are DOS 
routines and only "Write" requires information in specific regis- 
ters. I then MOVEd the current starting location to a temporary 
storage area called "stack," where it will remain until the end of 
the program. The address of the library name 1 want to open is 
stored inregisteral and the latest acceptable version— in this case 
— is stored in dO. Since the routine I want is in the EXEC library 
and that location is always in address 4, 1 stored a 4 in register a6. 
The JSR (Jump to SubRoutine) will transfer the program to a 
location -552 bytes from the EXEC address and open the DOS 
library. 

The result of the routine is to return the address of the DOS 
library in register dO. Most routines return the information re- 
quested in register dO. We'll store this address in a location called 
"dosbase." But what if the program couldn't find the library? In 
that case, register dO would contain a 0. Check for this with a BEQ 
(Branch if EQual to 0). The result of the last operation or proce- 
dure always gets stored in the CC (Condition Code) register. So 
if a was returned instead of a library address, the BEQ will 
branch to "done:". 

Put the DOSlibrary address in a6andthencall the "Output" 
routine saving the CLI console- handler location in "conhandler" 
and in d 1 . The location of the message is stored in d2 and its length 
of 23 characters in d3. Then the DOS "Write" routine is called to 
print the message; since C11RS{10) is part of the message, there 
will .ilsobea linefeed and anything else to be printed will goon 
the next line. 

Next, Ihe DOS library location is stored in dO as a 32 bit binary 
number. We want to print it, however, as a HEX number with 
eight characters, each character being through 9 or A through P; 
this corresponds to CHR$<#$30 through #$39 or #$41 through 
#S46). Since each HEX number is four bits long <#$F16 = 1 11 1 ,>, 
we need to convert each four-bit group into one CHRS value and 
put it in our buffer, and we'll need to do this eight times. 

The ROL (ROtate l.eft) command will help us out here. 
Whenever a byte, word, or long word is rotated, everything shifts 
over one space in the given direction, but the bit that gets bumped 
off goes around to the other end. Eight rotations would return a 
byte to its original value. First we'll store our buffer address in at) 
and clear d2and d3. Now rotate register dO #4 times to the left; the 
four left-most bits (31 - 28) arc now the four right-most bits (3 - 0). 
We want to keep using this value so copy it to register d2. Since 



all we want are those four bits, AND the register with #$F and 
everything else will be zeroes. D2 now contains a value from to 
15. Convert this to its CHRS value by adding #$30; if this value is 
between #$30 and #$39 branch to "ok." If the value is greater 
though, you'll have to add #7 to get theCHRS value for A through 
F. Now, store the string value at the location in register aO and 
increase a0 by one byte. The "+" after (aO) will increase that 
register by the size of the MOVE command. Since we've stored a 
string value in the buffer, increase the length in d3 by 1; keep 
doing this until d3 reaches 8. Use the CMP (CoMPare) command 
to see if a value and a register are the same. 

When the length reaches 8 we're almost ready to print the 
string buffer. As before, put the "conhandler" location in dl, the 
buffer address in d2, and the length plus #1 (we'll also print a 
linefeed) in d3. Again, call the "Write" routine and whatever is in 
the buffer gets printed as an eight-digit HEX number. 

After the entire routine, you have toclose the library opened 
at the beginning. "CloseLibrary" is an EXEC routine and requires 
the library address to be in register al. Any library that has been 
opened must be closed before ending the program. Again the 
EXEC location is stored in register a6 followed by a JSR to the 
"CloseLibrary" routine. This is followed by "done:". If the 
"OpenLibrary" routine hadn't worked, the program would have 
branched to here since there was no opened library. The contents 
of "stack" are restored to the SP register and the RTS returns to 
CLI. 

The EVEN command will align us on even addresses so that 
all of the following addresses will be acceptable. Three long word 
locations are reserved ("stack," "dosbase," and "conhandler") 
with DC.L and the eight byte buffer is reserved with DCB.B 8,0 
(Define Constant Block), followed by a CHRS(tO) for a linefeed. 
After some more EVENs, space for the library name and message 
are both reserved with DC.B. The message is followed by a 
CHR$(10) and both are terminated with a 0. 

After typing this program,save it as PR1NT_D0. ASM. Next, 
assemble it with A68K PR1NT_D0.ASM and when its error-free, 
blink it with BLINK PR1NT_DO.O. After saving the source code 
and program to the PROGRAMS: disk, type PRINT, DO and 
there's your message followed by the DOS library location. You 
could use this program to print the contents of any register, not 
just dO. In a future article we'll use some printer codes to add 
italics, underline, etc. 

A68K is very versatile. All of my programs are written with 
lower-case printing and that is acceptable. If you forget the S 
(Short), 1 (Immediate), or A (Address register), A68K will usuallv 
add it to the command for you. But try to get intothe habit of 
writing the best program you can and use A68K only to correct 
mistakes and assemble. 

IS THE FUTURE 

In the next article I'll show you how to write some macros 
that will make assembly even easier. We'll also teach our Amiga 
how to multiply and divide using fractions and even get it to talk 
to us! Future articles will discuss graphics as we explore the 
Mandelbrot/Julia Sets and work our way through arrays. Then 
it's on to Menus and Gadgets. I would keep re-reading the 
glossary of commands at the end of this article and add your own 
notes and comments to it. 
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Finally, then is no easy way to debug your program. 1/ the 
problem isn't obvious, sel It aside for a while then come back and 

try again. You could use PRINT.DO lo check the contents of 
various registers at different times in the program. Usually vour 
error will turn out to be some simple, dumb mistake and you 
won't believe that you didn't think of it earner. I try to write the 
entire program first in Basic and then convert portions of it to 
as-iembly Always save \ our program and changes before tmng 
them It you have any questions about these articles you may 
write to me through the magazine. 
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What's the best source of freely redistributable 
assembly langauge source code? 

Fred Fish Disks!!! 

from Your Number One Freely Redistributable Disk Source... 
Amazing Computing! 

Call 1-800-345-3360 



AC'S TECH™ 



Speeding Up The Drawing Process 



Programming 

the Amiga's GUI' in C— Part IV 



' Graphical User Interface 



Intuition's Border Function 

Due to popular request, this series, which was originall) intended to last only four 

issues, is being extended. I thank those readers who have mailed in let ten. of support. I also 
encourage others who would like to read about certain aspects of the Amiga's high-level 
operating system to make their requests known 

This issue contains a pleasant new tu ist Somewhere in this texl you will (ind a 
small programming challenge, a puzzle if you will. The first five readers to best solve the 
puzzle as described will win a one year subscription (or rcnew.il) ol/lCs TECH Magazine 
Mail entries to: 

Paul Castonguav 
P.O. Box 505 
Everett, MA 02149 

I have added this new feature for the purpose ol promoting more "Programming 
as a Hobby" on the Amiga. That's right, some people bought their Amiga* to have fun 
programming it. VVhv not? Compared to other platforms, it is a programmer's paradise 

In tins issue jfOU Will find: 

1. A Discussion of Intuition* high-level inn- drawing function, DrawBorttert I. 

2. Two implementations of Rosettes using OrawBorderi ). 

3. A discussion of Intuition'* tow level texl rendering function. Text! I. 
i of Intuition's high leivl text rendering function, PrintTTcxH ). 



4. A discussion of U 



The example programs in this issue all use the programming shell that we have 
developed over thecourseof the last three articles l-'or your convenience, a copy of it has been 
placed in each exampledirectory, along wit ha make f ile (Imkfile). It you make modifications 
to the programs you can conveniently re-compile bv entering I MK on the Amiga DOS 
command line, or by double-clicking the "Build" icon on the WorkBench. 

In this article, I use the term "line drawing " to mean a graphic image that is 
constructed of straight lines drawn be twivn an v number of defined points. In a future article 
I will discuss another kind of graphic image, one that is defined directly hv bitplane data 

With the last issue vou began drawing some simple image-- using the Amiga's 
primitive functions VVntel'ixel( ), Movef ). and Drawl ) These are probably the most often 
USCd graphic (unctions on the Amiga for creating line drawings Writel'ivelf ) illuminate- 
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Individual pixels on the screen, Movc< ) places the graphic cursor (or 
drawing point) at any desired location, and Draw( ) connects two 
points with a straight line. To create complex drawings using these 
functions, you write a series of instructions that mimic how you 
would produce the same thing yourself using pencil and paper. 

Speeding L'p the Drawing Process 

Often ihe points ot a drawing are based on some equation 
and require floating point arithmetic for their calculation, a task that 
is more time consuming than Integer arithmetic. In some cases we cm 
Overcome mil slowness by Using a programming trick: storing the 
calculated, pixel coordinate value* of all the points in a drawing in an 
integer array. I like to call this array the points-array. Once that is 
done, the Amiga's graphic functions can render the drawing at any 
time by using these values directly, without having to perform any 
further floating point calculations. 

A good example where this concept can be used to an 
advantage is in thedrawingof a rosette, which is buOl upby drawing 
a large number of straight lines between some smaller number ot pre- 
defined points, arranged at equal distances around the circumference 
of a circle, A 23-point rosette consists of some 253 lines Drawing all 
those lines using the original equations from which the points were 
defined, along with some reasonably adequate scaling functions, 
would require over 2000 floating point calculations. Instead we Can 
calculate the pixel numbers of those 23 points once and store them in 
an integer array. Then the repetitive invocations of the Drawl ) 
function, which produces the actual lines of the rosette, can use those 
pre-calculated values directly. 

A version of the rosette program is reproduced for you this 
month on the magazine disk, in the directory Rosettel. Observant 
readers will notice that I have added a macro definition, POINTS, to 
allow you to conveniently change the number of points in the 
drawing. I have also increased the size of the point-array 
(Rosette Points), to allow you to more conveniently draw rosettes 
having different point sizes. Now, compare the operating speed of 
that program with the one in the director)' called RosetteO. That 
difference in speed is due to the fact that the one in RosetteO is 
performing floating point calculations (or every line that it draws. 
while the other is using the above programming concept. 

Intuition 's High Uvel Drawing Function 

Intuition's high level, line drawing function, called 
DrawBordert ),can produce line drawings using this same concept of 
Muring pre-calculated pixels values man array. It renders bv drawing 
straight tines between points stored in the array sequentially, that is. 
in tandem 

As with most high-level operations in Intuition, there is a 
general operational theme to follow when using DrawBorderf, ): 

1. Declare one or more Border structures to contain the Spedfil I 
tions of your drawing, ihings like its color, how many point-- it 
has, ...etc. I like to call this the description structure 

2. Store the pre-calculated pixel numbers representing all the 
points in your drawing m an array such that drawing straight 
lines between them sequentially will reproduce it This may 
require thai some points be stored a multiple number of rimes 
at different positions in the array. I call this array the Border- 
data-array, to discriminate it from the one we used earlier in our 
rosette example. The Border-data-array must be located m chip 
RAM. ,i special section of memory that is addressable by the 
Amiga's graphic co-processor chips. 

3. Link all structures and their respective Border-data- arrays 
together. 

4. Invoke the DrawBorderl > function. 



I Ins general plan is a bit more complicated than using the 
primitivi M and Draw| ) functions direct I \ However, it has 

certain structural advantages, depending on exactly what kind ol 
drawing you want to produce, and it can render complex drawings 
verj fast I might also add at this point that the above operational 
theme is similar to that used in another Intuition, high-level function 
that I will discuss today, FnnllTexK > 

The Border (Description) Structure 

The template definition for the Border structure is m the lite 
<intuition/intuition h>. I reproduce it below without its comments: 

I 

SHOPT LvftEdge; 
SHORT Toj . 

ram 

E BarkPen; 
UBYTE OrawModv: 
BYTE C 
SHORT "XY; 
Btmct Bo: 
I 

LeftEdge and Top Edge refer to the position of the drawing, 

measured in pixels from those edges of its graphic window, ill have 

more to say about this later FrontPen is the color register (pen 
number) that you wish to use. There is no need to call Set APen{ ), as 
with the primitive graphics functions. Also, DrawBordert ) dins no! 
affect the current setting of SelAPen( ) 
BackPcn is currently unused by the DrawBorderl ) function. 

There are two ways that DrawBorder( ) can render draw- 
mi;-- I he first is called I AMI I his term means two things First thai 
the drawing will be reproduced using one color per Border struct ure. 
as specified in the Front Pen member, and second, that the drawing 
will overwrite ,m\ previously drawn graphic images 

This method effeclueh blasts your image down on the 
m teen, obliterating everything in its path. Note mat I AM I does not 
restrict you to only one color per drawing. Multiple colored drawings 
are rendered by building up multiple Border, graphic Structures, as 
you will soon see. 

The second way that DrawBorderl l renders drawings is 
called COMPLEMENT. In this mode the color is determined not by 
FrontPen, but by the binary complement of the drawing surface Foi 
example, if you are drawing on an eight color, blank screen, meaning 
that all pixels are color 0, then your image will be drawn in the bitwise 
complement of 0, which is color 7 However— and this is the interest 
ingpart— if your drawing overlaps any portions of previously drawn 
images or text, then those related pixels will be replaced, not by color 
7. but by whatever color is their bitwise complement The following 
chart lists bitwise complement colors for an eight-color screen. 
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The COMPLEMENT dntWirtg mode has the interesting 
property that it allows you to erase your image by drawing it agalnl 
But this is an advanced concept lor now, let's stick to the easier- to- 
use I AMI DrawMode. 

The count member of the Border description structure 
refers to the number of points (coordinate pairs) stored in the Border- 
data -array It represent- the number of points between whichstraight 
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lines will be sequentially drawn. This member is type BYTE and 
therefore cannot store values greater than 235. Thus 255 is the 
maximum number of points that the I>rawBorder( ) function can 
render from a single Border structure. Again, this is not a limitation 
since larger drawings can be produced by using multiple Border, 
graphic structures. The XY member is a pointer to the drawing's 
Border-data-array. In a minute, you will see two method* for declar- 
ing lh.it array so thai it properly resides In chip RAM. 

The last member of the border description structure is l 
pointer to another Border structure You use this member when you 
want to render complex drawings consisting of more that one Border 
structure, drawings that have more than one color, that consist of 
several discontiguous sets oi tines, or that have more than 254 lines 
In our lirst example, we will use only onestructure, in which case this 
member js assigned a NULL. 



Be : ivrtat 1 



[SHORT •(Ail 



1, HEHFCHIF I HEHF_CLEAftl i 



Whether your programsare complex graphics, or data base 
applications, allocating memory dynamically is the most efficient 
way to design them. They will use only as much memory as they 
need, when they need it. In addition, you will be able to allocate chip 
memory from within different functions, not just globally as in SAS/ 
C's chip data type I low-ever, this method does have the disadvan- 
tage that it is slightly more difficult to use. Your programs can often 
develop some difficult-to-dentify bugs. Simple errors can produce 
system crashes.Save your work often! 

The following code declares some memory and assigns to 
it the same data as the above rectangle example. Note that I used 5*2 
tospecifytheamountof memory, emphasizing that I need enough for 
5 coordinate pairs 



The Border-Data Array 

The purpose of ihis array is to store the pre-calculated pixel 

numbers of the various points of your drawing in such an order thai 

drawing straight lines between them sequentially will reproduce the 
drawing The amy itself must be accessible to the Amiga's graphic 
co-processor chips, and therefore must be declared in chip RAM. 
SAS/C makes that easy to do with their platform specific data type 
called chip. 

SHORT chip KyD*;.. 0. 0. 

100. D, 
100, 50. 

■ 

['he above array is declared in chip RAM M^i is initialized 
to the coordinates of a rectangle that is 100 pixels wide, and 50 pixels 
high. The data is in pixel numbers measured from the reference point 
defined in the LeftEdge and TopEdge members of the above Border 
structure. The SAS/C chip data type must be declared in the global 
section of your program, outside main( ) You don't have to worry 
about returning this memory to the operating system before your 
program terminates, the compiler takescare of that for vou automati- 
cally. 

A Dynamic Solution 

The above method is called static in the sense that it is fixed 
for only one si/e of drawing, in this case one having four lines 
Suppose you don't know, m advance, exactly how many lines are in 
vour drawing. Quick, tell how many are ina 27-point rosette? Do you 
sec what I mean? You could of course write code to calculate and 
report that answer easily enough, but in C you are not allowed to 
declare an array of variable si/e using the above notation. So even 
though your program is able to calculate the number of lines it needs 
to draw, it cannot declare .1 Bordcr-data-arrav of the proper size todo 
so. 

You could solve the above dilemma by declaring your 
Border data-array large enough to handle any drawing that comes 
along, but that would be impractical. Complex drawing are rendered 
by multiple Border, graphic structures, and their exact characteristics 
are impossible to predict in advance. 

The solution is to allocate memory dynamicallv. using 
■ >(. s AllocMem( > function. It requires two arguments, the number 
otln les that you need, which can becalculated by your program, and 
a macro specifying the kind of memory needed, in this case 
MEMF.CHIP Youcanalso use the convenient macro MEMF.CLEAR 
to initialize the arrav to zero. 
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This method of declaring the Border-data -array also gives 

vou the responsibility of returning the memory to the operating 
system before vour program terminates, using exec's FreeMemf ) 
function 

Linking Data to the Description Structure 

For Intuition to properly execute the DrawBorder( ) func- 
tion, the Border-data-array must be linked to the Border description 
structure representing the drawing. This is easily done with an 
assignment instruction. Below I give you a hierarchical diagram of 
what I have done so far 
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The Drawborderi ) Function 

After performingall the aboveground work, the only thing 
left to do is invoke the DrawBorderf ) function itself: 

DrawBordcr(BV_rp. fcMyBordar. x. y): 

This function renders the rectangle by drawing straight 
lines between the points stored in the array M\ ll.it. i It does this 
sequentially, as you would yourself if you were drawing while not 
being allowed to lift your pencil off the paper. To produce a closed 
image the first and last points must coincide. 

The first argument in the DrawBorder( > function is th<- 
forever ubiquitous RastPort pointer. The system needs it to deter- 
mine where you want your drawing rendered, in this case the 
window opened by your programming shell. The second argument 
is the address of the Border structure that describes the drawing you 
want rendered. The system will read from it your specifications, as 
well as the actual data points that you have previously linked to it via 
its XY pointer. The last two arguments are an offset coordinate pair 
that will get added to the position of every point in your drawing. 

Position Control 

You have three levels of control for the positions of points 
in your drawing: the LeftEdge and TopEdge members of the Border 
structure, the individual coordinates in the Border-data -array, and 
finally the offset coordinates of the DrawBorderf ) function 

LeftEdge and TopEdge represent a coordinate pair that act 
as a reference for all points controlled by that structure. This level of 
control is used when constructing multiple Border, graphic struc- 
tures, to adjust the relative positionsof different parts of thedrawing. 
The second level of control is the pixel data itself, which represents 
positions relative to the above LeftEdge and TopEdge. Finally the 
DrawBorderf ) offset value allows you to make one final adjustment 
to the position of the entire drawing. This is especially useful for 
adjusting the position of multiple Border, graphic images.asyou will 
soon see. 

First Border Example 

This first example draws theabove-mentioned rectangle. It 
is a single Border structure drawing; thus its NextBorder member is 
assigned a NULL The example is on the magazine disk in the 
directory called First_Border. 1 list it below: 
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• ■ iinti 



- :- 



(include <lMun . 

(include <»tdlo.h> 

■include catd 

(include <aitl 

• Include "pioto/in'.-. 

(include <proio/at4pniei.h> 

(include •pfoio'doi.h- 

I ■ Ida 'Shell. h' 



SHOT chip HyDalaU ■ I 0. 0. 

100. 0. 

100. SO. 

0. 

■truet Border HyBorder * ( 



• mom LeCtHge 
■ SB M TopMp 



.'AMI. 

'• BYTE Count 

KyData. ." SHOST 'tl 

/• itiuct border 'HextBordei •/ 






VOID Micont argc, char ••r^vili; 

VOlDwemUm «gc. char ■«rflv!|l 
I 

struct Screen •By.sereen: 
■ viewport *«y_ivp; 

■trace Window *By_*indow: 

itiuct RaitFort *-. 

mom . . 

lt(;Open.SheIlH^_icreen, l»y_avp. l»y_wlnda». l«y_rp, •UtEHICHB'M 

printfrftotilea* inOpen_Shel; 

DeleyUOOli 

e*iURnwu. 






r>... •/ 



forii • 0; i < S; ... 

Dra-Boiderlay.rp. fcKyBotdei. i«ic. ' 

S«tAP«H*y_rp. II; 

Hovetay.rp, 230, 10): 

T«tl«y_rp. -Beetanfllw mine, DraiA: 

DelaylSOO); 

'• ■"•• •-: n- ;..* 

Clo«e_She;ii»y_windcw. *,_icreer.ri 



This is a static solution. The Border-data-array is declared 
globally using SAS/C's chip data type. Notice that the drawing's 
Border structure is also declared globally, although strictly speaking 
that was not necessary. I did so in order to keep the two related 
declarations close together in the listing. The program con tains a loop 
that draws several instances of the rectangle using DrawBorderf }'s 
offset feature. What you have here is fivedrawings produced from a 
single Border, graphic structure by multiple invocations of the 
DrawBorderf ) function, each at a different position on the screen. 

The nextexample.Second_Border.c. demonstrates the same 
program except that the Border-data-array is declared dynamically 
and private to main( ). Note that two new finclude's were needed: 
<cxec/memory.h> which contains the macro definition for 
MEMF_CHIP. and <proto/exec.h> which contains the ANSI proto- 
type definitions of the AllocMemf ) and FreeMeml ) functions 



/• Second_Bo[d«r.c 
Paul Castonguay 



October. I9!l 



- intuit. on. hi 
1 '■- «e*ec'*e*ory.h> 

(include <»tdio.h> 
(include <«tdlib.fi. 
(include auth.h> 
(include •proto/lntulticn.h> 
•include <proto/graphici.h,> 
' it <proto/do*.h> 

•include <proto/ex*c.b> 



• 



unclad* •Shell. ft- 



VOIDittiniint argc, char •argvll): 

VOID Minimi atge. char 'argv[|l 

■truct Screen **y_icre«n; 

'"i.lvp; 
ltruct Window ••y.windowi 
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NextBorder = NULL 
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*•• (last structure in list points to NULL! 



Rosettes Using DrawBordeH) 

The DrawBorderf ) function is not limited to simple draw- 
ings. Let me demonstrate by using it to render a rosette. Recall that I 
introduced the rosette early in this series, promising to use it laid to 
demonstrate different programming concepts. It's more interesting 
than rectangles, don't you think? 

In order to make the program capable of efficiently draw- 
ing rosettes of different point sizes, I will declare whatever memory 
it needs dynamically. The larger the rosette, the more memory it will 
use for its graphic data structures. Also you will see that the amount 
of memory used depends on how ingeniously we design the pro- 
gram. 

Now, exactly how can we design a bunch of linked Border 
structures to represent a rosette? Perhaps we could divide the rosette 
into groups of lines having some similar property? Well, that could 
work in principle. A natural division might be in groups that connect 
to one common point Each group would represent a fan pattern of 
lines. The trouble is, DrawBorderf ) draws lines in tandem, connect- 
ing points that are stored in a Border-data-array sequentially. That's 
great for drawing closed figures, like polygons, but not very efficient 
for fan patterns. The computer would have to trace back over each 
line that it drew in order to get back to their common point before 
drawing the next one. That's too time consuming. 

One answer is to divide the rosette up into individual lines, 
making a separate Border structure for each. That's an awful lot of 
Border structures, but the Amiga can handle il easily All these 
structures must be linked together and each one linked to four data 
values (two points, each having horizontal and vertical coordinates) 
stored in chip RAM. Sound complicated? It's easier than you think. 



andagood demonstration of Intuition's high level power as well. The 
solution is on disk in the directory Roserte2 I explain its internal 
operation below. 

The first order olbusini'ss is [ouikui.ile the number of lin.'s 
in the rosette. To do that we use the same double nested loop thai 
normally generates it. except that here we only increment a line 
counter: 



■ ■ nuabei c I 

ford 
for I j 

lire_coun' - • 



You can put a print instruction after this loop and confirm 
that the exact number of lines in a 23-poinl rosette is 253 Next we 
allocate memory for our graphic structures 



Allocate Boid.-- 

'" •'■' 

.... 

■ ■ 

Allocate Boir;. 

Koo*lte_Bord«r 

AllocM< - irdrn . 



The first declaration, Rosette_L)ala, will be used tostorc our 
pixels numbers. It is one contiguous length of chip memory, long 
enough to store 4 four integers per line of the rosette The second 
memory declaration is lor thearray of Border structures, one tor each 
line. This one need not be in chip RAM. Each Border structure will 
have to point to a different spot in the previously declared length of 
chip RAM Rosette_Data. 

Now we need to calculate the pixel numbers for the points 
of the rosette. We use a point-array for this, for the same reason that 
we did in our earlier rosette examples, to keep the number of floating 
point calculations in our program as low as possible. Note that this is 
not lh«' data that DrawBorderf ) will use dinitly. but rather the data 
that we will use to fill upchip memory with thedata that DrawBorderi 
) will use. 



■■■■■■■■■■■■■■a 

>.- Calculate and store point 






RadtAjv: 
Pad (At. | 



Mtri«i * 



We then assign data to chip memory using these pre- 
calculati'd values, thus: 



■ 

■ ■ 
tor 
I 



l.oop througr. assigning end point! 






itai 

■ 



•Data_ptr.. 

'Data.; 

•Data_ptr-- 
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IttWt KastPort '■j'.rpf 

SHORT *KyDit* • HULL I 
SHORT 'p-r - WJtL; 
SHOUT 1; 
struct Border MyBorder; 



l(l!OD«n_Sb»llfWy_»crMn, kay.svp. Uv_t.iftdow. iay.ip, •LACEHIGHB'l i 

•Probl«M in Optn. I - 
MtyllOQIi 



r«l code rt«n fieie 



MyDiU = iSHOfll ■iXlloc-m 

■ 



■ ■■ 

■ ■■ 



100 i 



100; 

SO; 



• 

MyBortfer.LeiiEdQ* 
HyBordet .TopEdc* 
HyBordei .FroniPen 
l«y8otd*r.B*MPtn 
HyBoid>f.DrawKoa> 
MyBordet .Count 
HyBoiitaf.xr 



■ 
■ 1; 
• 0: 

' *yD*:a: 



Oraw9ord*r(ay_ip. fcHyBoid*;. - 
Delay 1500): 

FrttMMlMyData, S'^'iijeo! iSHOflTl I; 

■ *•• Com ibfll b> 
Clote_Shell{*r_wiftdow, ffy_nrr**r.h 



Exactly what method you use to declare your array will 
depend on the structure of your program. If you are drawing some- 
thing whose definition is known at the time you are writing the 
program, and which is used in several places wilhin your program, 
it may be more convenient for you to use the global version. How- 
ever, if you must rely on internal calculations to define points in your 
drawing, you will need to use the dynamic method But even if your 
drawing iscompleti-ly known ahead of time, you may still need to use 
the dynamic method. Any program that is reasonably complex 
should be structured into functions and have its graphic structures 
made local, in order that you can come to grips with its overall 
complexity. Program structure is not a strict rule that you must follow 
to get your programs working, but a feature that you should use to 
make them maintainable. Authors of unstructured programs lead 
lonely lives because no one can understand their work. 

Drawings in Multiple Colors 

If you have a drawing that consists of a single border 
structure and you want to render it in different colors.and at different 
locations on the screen, you have a number of choices. Vou could 



change the Front Pen member of the Border description structure 
before every invocation of DrawBorderf ), which might then render 
it using different offset coordinates. Or, you could create several 
Border structures, each having the same U-ftEdge and TopEdge 
coordinates, pointing to the same Border-data-array, but having 
different Front Pen definitions. Then each invocation of DrawBorderf 
) would specify the address of a different Border structure, as well as 
different offset coordinates of course. An easy way to do that is to 
declare an array of Border structures, as in example Third _Border.c 
on the magazine disk. I reproduce the important parts below 

* 

HULL) 



rd« KyBord*rlSI: 



KyEfctt ■ 'S* 

My OKa i 

0; 
. , Qi 

■ . IQOi 

Cj 

■ 

■ ■ -50; 

0; 
•ptr-- 

■ 

0; 

■■ 

Ky Barter Ul-Xt Mop 

■ 

. . . 
HyftorterUi.&«*Pen 

■ ■- ■ 

■ 
HyBottet . .. .K**tBord«r 



.1H0RT). MWJMIP I KOtf.CUM); 



• difteient color (or etcfi '/ 
• Of 

■ 

■ S; 

> HyDa'.t; 

■ HULL; 



,_:p. MtyBorderUJ. i< 



•: 



Note that in each case the DrawBordcr( ) function renders 
a drawing represented by a different Border structure, but having the 
same pixel data. The Border structures are not linked. 

Linked Border Structures 

Another way to display colored rectangles is to declare 
several Border structures, each one having its own FrontPen color, M 
well as its own LeftEdge and TopEdge coordinates, and then link 
them all together using the NextBorder member. This is your first 
example of a drawing represented by a multiple Border, graphic 
Structure. The structures are linked sequentially by having the 
NextBorder member of each point to the Border structure of another, 
with the last one pointing to NULL. This is the old linked list Idea thai 
you learn about in any computer-science data -structures course. 

The big difference in this example is that only a single 
invocation of DrawBorder( ) is required to render all five rectangles 
See example Fourth, Border. c on the magazine disk, which draws 
two complete drawings, 10 rectangles, using two invocations of 
DrawBorderf ), each using different offset coordinates. Below I give 
a partial hierarchical diagram of the structure which represents the 
drawing (next page): 
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The Data^ptr pointer jumps along Ihe contiguous length of 
chip memory assigning pi<co! coordinate* .that represent end points or 

all the lines in (he roselle The last piece ot work is the assignment and 
linkage of the Border structures 



■ 

Assign and link border 
I' ■>• and Bon)> 

RoMt t«_Bo r de r_p * 

for u • Q: 



Ro8«tte_Botdei 

■ 
. . . 

■ 
Rolette 

■ 
Pose:.' - -XY 

1 ine_ec . 



• JAM1; 

■ 



I 



■ - 



Roaette_Bo: 






■_Bord*r_pt r- .Next border 



We use a pointer, Kosette_Border_ptr, to jump along the 
section of memory representing the structures, assigning members as 
we go along. Each XY member is linked to the pixel data of its 
respective line in chip memory, four integers representing two coor- 
dinateson the 3Cmfl ITie Count member of each Border structure is 
only 2. meaning th.it each one will draw a single line between two 
points The last Border structure is made to point to NUL1 p represent- 
ing the end of the linked list. 



Rosette Border[0] 
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■•• (last structure in list points to NULL! 



All that done, we can now invoke a single DrawBorder( ) instruction: 

Dram!' i 01. 0. Ol j 

... and presto, our rosette gets drawn. Like magic. 

Perhaps you are thinking that all of this is too complicated 
to be useful. To draw a single rosette? Perhaps. But what if you 
wanted to draw many rosettes, perhaps at different places on the 
screen. Once you haveconstructed the graphic structures, a drawing 
can be rendered at any time by a single Draw Border! ) instruction. 
Example Rosette3on disk does that First it scales the screen such thai 
the origin is m the center of the top left quadrant of the s, reen 



ifdScale 
I 

Cloie_; 






Then the graphic structures are constructed as before. Finally four 
different Rosettes are rendered like so: 

:«*• h 

■■ .0. FYW.C 

B r a— i ll r ^_f». thw i . .8]-fxiO.0l. 



I wanted to use the Fx( ) and Fyl ) scaling functions to make 
(he placement of each rosette easier to visualize. To do that. 1 had to 
remember that the offset argument of DrawBorder( ) is added, not to 
my Cartesian coordinates, but lo the lop left corner of (he window in 
which my drawing is being rendered. The graphic data structures 
were set up such that the center of the rosette is at Cartesian coordi- 
na tes<0,0>, which corresponds to pixel coordinates Fx(O.O), Fy(O.O). To 
shift the rosette to a different position requires that I subtract those 
Fx(0.0| and Fy(O.O) terms from each new location 

Rosettes are only an example that I chose to use because 
the] are slightly more interesting than rectangles. The purpose ol all 
this is lo help you learn how louse the DrawBorderf (function. I really 
don't know what kind of drawing you will want to render. But 
whatever il is. you will probably want to build it up in a structured 
manner, using a different Border structure tor each section of the 
drawing 

Another Implementation of Rosette 

Although the above example is certainly a good one for 
showing a complex graphic structure, it does not make most efficient 
use of memory. The problem has to do with the repetition of coordi- 
nate \ alues in the Border-data-arravs You see, each line is defined by 
two end points and consequently each Border structure points to a 
four-element array. But often the beginning point of one line is the 
same as the end point of another. One would think thai different 
Border structures could share the data for those common points. But 
the above algorithm does not take advantage of that. To design a 
program thatdoes.wecoulddivide the linesof the rosette into groups 
of contiguous lines, that is. lines that consist ol several segments 
drawn in tandem Then points that are common to two segments 
would not have to be repeated. 

Suppose you start at one point on the rosette and draw a line 
to another immediately adjacent one. Now, moving in the same 
direction draw another line, (his time not to the next immediately 
adjacent but to the one alter that That is, skip a point. Continuing. 
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draw mother line, this time skipping two points, then another, this 

tim.' skipping three... .etc. The result will bea kind of spiral that traces 

3 unique path through the rosette I low many such steps can be taken 
by ,1 single line? In a 23-poinl rosette, only 11 Alter that the line is M 
longer unique and will start drawing certain lines for thesecond time. 
However.if you go back tothe point where that lim- started and move 
over one point, you can begin another similar. 1 1 -segment unique 
line. And, how many timescan you do this? You guessed it, 23 times' 
Thus you can complete the entire rosette by drawing 23 contiguous 
lines, each one consisting of 1 1 sections 

The example program in the directory called Rosette2A 
solves the rosette using this new technique lt> graphic structure 
consists of 23 linked Border structures, each rendering a unique 1 1 - 
segment path through the rosette. The example demonstrates hOM 
ingenious methods can be used to reduce the si/e of the graphic 
structures. It also demonstrates the perils of dvn.inuc programming. 
that 3 right, the example is programmed dynamically and will 
render rosettes of anv size up to 49 points simply bv changing the 
macro POINTS. 

Here is the memory allocation for the Border_data amy 

_ im (SHORT • 
WW 



\S e pick a point on the rosette, line_set, then increment by 
ever increasing step sizes until II line segments are completed 
(line COUnt/POINTS). Notice how I use the modulus operator, %, to 
wrap around through values in the Rosette, Pomt> amy. We then 
increment Iine_sel and st.irt the next contiguous 1 1 -segment line 

That done, we must now link the 23 Border structures to 
each other, and to their respective Border-data-arrays. 
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■■-ie_Bord« J 



We multiply the line_count by 2, not 4, because this method 
takes advantage ot using common points to draw contiguous lines 
But watch out tor the trap. You must add 23 extra points (POINTS) 
because there ire 23 separate line sets, each having 2 end points which 
are not shared. Fail to see that and you will crash your machine 

1 lere is the memory allocation for the Border structures 
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Next we must assign data to the Border_daia ami) , 
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in thu Sordf: 
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Each XY pointer is linked to its respective line set. But wail 
a minute. Each line sei consists of 1 1 segments and of course two end 
points, That makes 12 points, not 11. Note that at this point in the 
program, the variable "points" does not equal 11. It equals 12, cvi, t!\ 
what we need. It became 12 when it exceeded the upper limit of the 
previous do loop. Tricky, eh? Each NextBorder is linked to the next 
Border structure, except tor the last one which is assigned a NULL. 
I'he result of all this is a graphic structure that occupies better than 
halt the memory of the previous example, yet produces the same 
drawing. 

Programming Challenge 

Is there a wav to program the rosette using a single Border 
structure > ^ es there i>. bill it has. in upper limit That is, there isa limit 
In the point size ol l rosette that can be programmed using a single 
Border structure. Can you find it? 

Think about it, you have to design a single Border structure 
to draw a contiguous line (hat produces a complete rosette. 1 did not 
Say that the line could not double up on itself, it can. But to produce 
the largest rosette possible, and remain within the upper limit of the 
Count member of the Border structure, it will have to draw in the 
most efficient way, Actually Rosette2A isa good hint on how to do it, 
Youi solution must be programmed dynamically, to make most 
nt use of memory, and it must be generalized to accept any 
POIN I si/e up to its upper limit. You may use the simple method of 
defining a macro for the 1*01X1 size, as I did in this article To test 
your program, simply change the macro and re-compi!e. If your 
programming skills are up to it, you may use command line argu- 
ments, or. my other legitimate form of input, to enter different POINT 
Bizi s |(,it vour solution must indeed produce a complete rosette for 
each POINT si/e up to its upper limit. It must also correctly handle the 
case when the point size is ten) high Sum . no svstem crashes are 
allowed. 

Cft\f luck! 
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The directory oiled RosetteZB contains one last example, 
which 15 equivalent to the one in Rosette2A except that its Count 
member has been reduced by 1 Many interesting, artistil patterns 
can be discovered by making small modifications to the types of 
example programs we have been using 

line Animation 

Don't fall into the trap of thinking that DrawBorder( } is 
useful only for static drawings. It can be used for animations .is well 
A good example is the Line_ Animation program front two issues ago 
You remember that one, don't you? It drew a line that left a trail as it 
moved around the screen. I'erhaps you were not too impressed with 
it Alter .ill. there is, i similar one on the SAS/C examples disk that is 
10 times taster Hut wait, there is a big difference. Run the SAS/C 
example and you will see that as the trail is removed (by drawing the 
last line in the background color) it overwrites portions of the 
remainder of the trail I know it's moving so fast you can hardly see 
it, but by pressing the right mouse button you will temporarily stop 
it and be able to see the effect I am talking about Mv version does not 
do that. By relying on the fast drawing speed of DrawBorder) ), I was 
able to redraw all lines in the pattern every time the last one was 
removed. The effect is a much smoother animation. 

1 promised in that earlier issue that I would use the 
Une_ Animation example in future articles to teach certain program- 
ming concepts, and I will, just as I did this issue with the rosette. It's 
just a little too soon yet for animation. In case vou did not see the 
Line_ Animation program, you will find a compiled version of it Oil 
disk this issue. 

Rendering Texi 

You have seen mc slip in without explanation a few text 
instructions in all the examples ot this series It i> now tune to sav a 
few words about that. Asm the case of rendering line drawings, there 
are two ways to render text on the Amiga, a primitive way and a high- 
level way. 

I'rimitiveTexH ) Function 

The Text( ) function is pari of the Amiga's graphs -. Iibrarv. 
which is automatically opened for vou by the programming shell 
Here is an example of its use 



S«tAP«n(my_;; 
Hove(my_rp. 0. 10); 
■y_rp, 'Hi 



nil 



Initially you must select a pen register, and move the 
graphic cursor (drawing point) to the place on the screen where you 
want the text to appear The Text( > function itself requires three 
arguments. The first is the RastPort pointer, representing the window 
in which you want the text rendered The second is the text itself, or 
a pointer to a NULL terminate.! length ot memory containing it- 
more about that in a minute. The last argument is the number ol 
characters in the string. 

Baseline of a Font 

The word font refers to thecharactenstics of the letters us.\l 
by the computer for displaying text on the screen. The Amiga has ten 
different fonts, with names like topaz, diamond, ruby, ... etc. They .ill 
come in a variety of si/es In this article 1 will discuss only one. the 
Amiga's default font called TOPAZ.EIGI I IV 



To place text at precise locations on the screen, you must 
have some knowledge about the font you are using. Specifically you 
miisi know the location of its baseline, the point in its graphic 

definition from which it will be rendered; its graphic re f ere n ce point 

if you will. In previous examples I have used the number 10 as a 
vertical coordinate in the Move! ) function when I wanted to place 
tevl near the top of the screen. I chose that number to guarantee that 
the text would appear properly within the limits of the window, 
while at the same time not over-complicate the appearance of mv 
code. But thai was not quite correct. To place text properly, 1 should 
have used the font's baseline detinition. 

The height of a font is measured in scan lines starting from 
the top of the letters. The Amiga's default font, TOPAZ_EIGHTY J is 
defined in the header file <intuition/prelerences.h> to be eight lines 
high, numbered trom l) to ? In addition, us baseline is defined (in a 

different place) tobeonelineup from the bottom, or line number 6. 

But of course one should never go around using absolute numbers for 
such things 1 he user could easily change the default font, in which 
.a-ethecurrentfont'sbaseline would be different and the portioning 
of the graphic cursor in your program wrong The solution to all this 
is to read the baseline of the current font Irom the system It is kept in 
tlie Rastl'ort structure, in a member called TxBaseline. 
Below 1 show my above example modified to do this: 

" 

■ 

Now 1 need never worry about the text accidentally o\ er 
shooting the upper edge of the window. The exad top line of the 
letters will always coincide with the exad top ot the window I he 
user can change the system font and my program will comply by 
using the baseline of his selection. 

Building Your Strings 

Remember that unlike BASIC, there are no real string 
variables in C. You have to build them up yourself by declaring 
character arrays and then copying texl into them PageU68ol vow 
SAS/C documentation lists four different functions thai vou can use 

to do this, each one having its own advantages. I like to use steep W ) 
tor a tew reasons. First, its operation is always limited to some fixed 
number of characters that must be specified Thai protects vou from 
the disaster (possible system crash) ol accidental!} COpJ ing strings 
that are not properly \L I I terminated Second, when StCCpyt I 
encounters,! NLfl L character in the source string, it fills the remain- 
der Ol the destination string with NULLS, up to the length you 
specify. Third, it guarantees that the List character of the destination 
string is a NULL character, even it the souree string is (accidentally) 
longer than the destination Finally, it returns the length of the string 

copied, convenient for use in the Amiga's lexr) > rendering function, 

Here is an example 

1 

char %, 



■ 
Jtov*iP, _ 

1 must subtract 1 from size because slccpyl 1 repor ts length 
including the terminating NULL character. Of course vou may have 
your own legitimate reasons for wanting to use another one of SAS/ 
(. S string copying functions, or even one of your own design 
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Using SprintF( ) 

You are probably wondering how lo go about displaying 
numeric values inlo a graphic window. Intuition is not like a CLI 
window; you cannol use the normal Standard C print(( ) instruction. 
In fact, 1 1 your program executes a printff ), its text goes, not to your 
programming shell window, but to the CLI (or AmigaDOS Shell) 
window (rom which you launched the program, what is called 
standard I/O. 

A convenient function to use for getting numeric values 
into a graphics window is sprintff ). It does everything printf( ) does, 
except that it sends the text to a previously declared char array, 
instead of stdio. It even returns the length of the formatted string 
produced. From there it can be easily used by Amiga's Text( ) 
function. 



Intuition s High Level Text Function 

Just as there exists a high-level Intuition, line-drawing 
function, there also exists an equivalent text-rendering one, called 
Print IText( ). Here is its operational theme: 

1. Declare one or more IntuiText structures to contain the specifica- 
tions of the text you want rendered: its color, position, font, ... etc. 
1 like to call this the description structure. 

2. Store the actual text you want rendered in a NULL terminated 
character artav. 

3. Link all structures and their respective text-arrays together. 

4. Invoke the Print IText( ) function. 

Depending on exactly what kind of text you want rendered, 
there may be advantages to using PnntIText( ) over the more primi- 
tive Texrf >. 
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The sprintf) ) function allows you to use all the formatting 
conventions of Standard C to build strings that you can then render 
into any graphics window. 

TextAttr Structure 

The programming shell window of these articles does not 
automatically support scrolling and carriage returns like a CLI or 
Am igaDOS Shell window. You have to keep track of where todisplay 
successive lines of text yourself. The minimum that you need to know 
is the height of thecurrent font. That, after all, is what determines how 
many lines of text can appear on the screen, and how they should be 
spaced for best appearance. Font height can be read from the system 
by using tho AskFonif ) function in conjunction with a TextAttr (text 
attribute) structure 

The TextAttr structure is defined in the <graphics/text.h> 
header file thus: 
struct TextAttr 



sntfT* 

UHORO 
UBYTE 
UHVTG 



■ UtOMJ 

C«L,YSiMJ 

la.Style; 
la.Flatjs; 



1; 



/• name o( the font »/ 

.nsic lont sty I 
'" font preferences and (lays •/ 



AskFont( ) is a function in the Amiga's graphics library. It 
can be used to obtain the above information about the current font. It 
requires that you previously declare a TextAttr structure in which to 
report the information. 

struct TextAttr def»ult_Attr; 
AskFont <my_rp, tdefajlt_-- 

You can then read the height of the current font from that structure: 

Iine_neiQht - doIault_Attr .ia_YSi;e • 2; 



Some Background 

All text consists of two parts, the letters themselves, called 
the foreground, and the background area over which they appear. 
For example, in TOPAZ_EIGHTY, each character is formed on an 8x8 
pixel grid by illuminating certain pixels, while .il the same time 
leaving certain others off. The pixels that are illuminated form the 
actual character and are called the foreground. Those that are left off 
are called the background 

The Amiga can render text in four different ways, described 
by its different DrawModes. The first is called (AMI, trie same term 
that you saw earlier in DrawBorderf ). In J AMI, mode text is rendered 
such that the foreground of each character over-writes any previ- 
ously drawn graphics or text, but the background does not. Thus the 
computer is rendering in one color only, the foreground color. A 
second mode, called JAM2, renders text in such a way that both 
foreground and background over-write previously rendered graph- 
ics or text. Thus the computer is drawing in two colors, the fore- 
ground color and the background color. A third mode, called 
COMPLEMENT, renders text such that all foreground pixels are 
replaced by their binary complement. The last mode, called 
INVERSVID, reverses the roles of the foreground and background 
colors. 

IntuiText Description Structure 

The template definition for the IntuiText structure is in the 
file <intuition/intuition.h>. I reproduce it below without its com- 
ments: 



struct 
I 



Ent 'i: 7<-j". 



UBYTE Front Pen; 

UBYTE BachPen; 

UBYTE DcawModo: 

SHORT Lett Edge; 

SHORT TopEdge; 

Struct TextAttr 'ITextFont; 

UBYTE 'ITcxt; 

struct IntuiText 'NextTcxt; 



I assign linejieight to be two scan lines greater that the 
actual font in order that the text appears properly spaced on the 
screen. Two scan line-- work out pretty well for TOPAZ-EIGHTY. 

See the example St ringvc, in the directory Display_Text, on 
the magazine disk. It shows you how to use a variable, called 
line„number, to keep track of where to render successive lines of text 
to the screen. The example also contains the previously mentioned 
sprintff ) function, reporting a floating point value to screen. 



FrontPen is set to whatever color register you want for the 
foreground of the text. BackPen is set for the background. DrawMode 
is set toeitherJAMUAM2,COMFLEMENT.or INVERSVID. LeftEdge 
and TopFdge determine the position of the text in the window 
TopEdge refers to the position of the top scan line of the text, not to 
the baseline as was the case with the Textf ) function. The ITextFont 
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member points to the structure which describes the font you want to 
use, or NULL if you want the system's default font. I will leave this 
NULL today. IText is a pointer to a NULL terminated contiguous 
section of memory containing the actual string that you want dis- 
played. Finally NextText points to another IntuiText structure > on 
use this last member u your text consists ol many strings, each one 
represented by a different IntuiText structure. Below I give a hierar- 
chical drawing of a properly constructed IntuiText structure that 
displays a single string message at the very top left corner of the 
window. It uses the system's default font, color register 1 for fore- 
ground, and color registerO for background Its NextTexl member is 
assigned a NULL, meaning that I have only one string. 



Profit :•■: 

backPan 

m .-V >■ 
Left Edge 
Toptd-je 
IText Font 

ITex; 

Next Text 



- JAM2 

- 

i NULL 



Help av. I'm 01 . 



NULL 



The actual rendering is accomplished by the PnntlTe\t( I function; 
■•xtloy^rp. iMy_IToxr . X. 



... which requires tour arguments, the RastPort pointer, the address 
of IntuiText description structure, and an ottset coordinate pair that 
has a similar purpose to its equivalent in Draw border( >. 

TheexamplelText cinlhedirectory Display J Text, demon- 
strates one way of using Intuition's PrintlTextf. ) function to display 
an entire screen of text It opens an interlace screen, enough room for 
50 lines in TOPAZ.EIGHTY. It then declares a 50-dement array of 
IntuiText structure-, one tor each line on the screen, and a character 
array called my_stnng(50|lH0], enough memory space for 80 charac- 
ters on each line. (79 actually, remember the 'Ml' character?) The 
IntuiText >tructuros are then linked together and each one made l.« 
point to its own 80-character section of memory. The TopEdge 
member of each IntuiText structure is asMgned a different vertical 
position, thus placing each line at its correct location on the -* reen 
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Text can be copied into the character array using stccpy( ). 
It's easy to keep track of things because the element numbers in the 
character array correspond to lines on the screen. Finally the entire 
structure is rendered using a single PrintFTextf ) instruction It \ ou 
run the example, please do not try to read the text on the screen; it 
doesn't stay there long enough. Theexampleisintended only to show 
you how PrintlTexti ) can be used. It also shows how to clear the 
screen and the 50x80 character array in order to display new text 



nu-ance, n. 

a delicate degree 
of difference. 

1 Y|"--ilit»i; quality is In the <lct.nl>, (fetalis often omitted for Ion* 
list* of feature*. Detail* such as separate hyphens {-), en-dashe*. ( ). 
Mid errwlaabes I Detail* inch aa ligature* and kerns. Details 

such as vertical justification and a full range of diatrical marks Hut 

then i- no loojpa any need to compromise- you can have all of the 
features ami all of the quality with 

AmigaT^ 

Many product* allow you to import PostScript graphic! from any 
source AmifaTtfjX allow* you to preview thou grapbli ion the screen 
and prinl them to any prino-r even -lot-matrix printers. Some pro- 
grams allow you to use PostScript foni-«. Ainignl]--N l<t- you use 
both Type j and hinted Type 1 outline fonts, on the screen and to 
any printer Some packa*.". .i]|ov, importing IFF/ILBM imager but 
none provide the variety of dithering and filtering 
with AmigalbX 

Multi-thousand page document* present no difficulties, even on a one 
megabyte Amiga Matheitiatii ■■ and l.il.l.--. .-in- tvpeset with unparal- 
leled quality If you are serious about putting words on paper, write 
for your free demo disk. Move up to the cpiality of AinigaTi^X 
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Circle 102 on RmSk Service c*<a 

For some simple text oriented program! thus may be all the 
screen design that yon need. It is easy to set up, uses high level 
language concepts, and renders tad extreme!) fast Naturally it 

should be structured into sever.il functions before making it part of 
any application 

Sexl Issue 

This last example demonstrates a shortcoming of all my 

programming example* so far, that thev remain on screen for only a 
predetermined period of time I design them that wav m order to ktvp 
them simple at these early stages However, in the next issue I will 
present the missing link that will allow us to control programs using 
the mouse or keyboard, the Amiga's message system. 
1 will also present the Amiga's disk based font system and how you 

can use any one of them in your programs, 

Paul Catougwiu loves to hear from readers'. Please send your comments to 
Paul Castongauy. P.O. Box 505, Everett, MA 02149. Additiomli 
can write to Pau'lc/oACs TECH, P.O Box 2140. Fall Rnvr. MA 02722- 
2140. We will forward your tetter* to Paul. 
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Recently, we were ordered by 
U.S. military officials to explain to 
their complete satisfaction just 
what a SuperSub is (as we all 
know, it's the best subscription 
deal around for Amiga users, 
since it includes both Amazing 
Computing zndACs GUIDE). 



».v.v; ( 



I hen, a prominent Congressman 
wired to ask us if we would testify 
before a top-secret subcommittee 
as to whether or not we can pro- 
duce a single prototype SuperSub 
for less than $500 million (is this 
guy kidding? - a one-year 
SuperSub costs just $36 - and we 
can produce one for anybody!). 

.Y:r.V,Y.V 

rinally, a gentleman called us 
from Kennebunkport and told us 
to read his lips, but we told him 
we couldn't, because we don't 
have a picturephone. 

And then he ordered a SuperSub. 



AG's SuperSub - 
It's Right For You! 

call 1-800-345-3360 
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The Development of a 

Ray Tracer 



Part Two: The Implementation 



by Bruno Costa 



In the first part of this article, some of Ihe essential ray- 
tracing concepts were presented, including a dcscriplion of a 
simple illumination model. This second part is dedicated to show 
the practical usage of that theory, with many commented ex- 
cerpts of code from a real ray tracer (called "ray"), that is included 
on disk with the full source code in C. Some references will be 
made to the first pari of the article, and, although not strictly 
net essary, it is recommended that you try to understand that part 
before reading on. If you are not specifically interested in ray 
tracing, it may be worthwhile to examine just the object orienta- 
tion sections. 

The General Structure 

I he outline of the basic ray-tracing algorithm presented in 
the previous issue revealed how simple it can be. It was men- 
tioned that what distinguishes a good ray tracer are the special 
features II has, besides the almost standard ray-tracing kernel. 
This is one ot the reasons why ray tracers are not merely a few 
hundred lines long. Another important factor is the code neces- 
sary for each kind of object, the various data types (likecolors and 
vectors) and the output device d riven 

Since ray tracing needs to know some features of each kind 
of object it is supposed to render— how to calculate an intercep- 
tion of the object with a ray, for instance— additional code is 
needed to support each class of objects. These classes of objects 
are often called primitives, because they can be combined to 
produce much more complex objects 

Some libraries and routines are used by all other parts of the 
program to help in manipulating 3D vectors, colors, lists of 
objects, parse command line options and handle errors— they 
comprise the support .ode Also important are the routines that 
communicate with the output devices (like an Intuition HAM 
screen, an I IT file, or a 24-bit frame buffer), which guarantee some 
device limitations or restrictions and also perform any necessary 
steps to control the hardware or software involved. 

With these classifications in mind, a good organization for 
.1 m\ tracer could be the one given by figure I The user sees 
simply a front-end, called "ray," that controls the ray-tracing 
kernel. To do the real ray tracing, the kernel needs to call each 
primitive todelermine some of its features, and the output device 
driver to show or store the resulting picture. The various small 
packages in the support code are called by all other parts ol the 
program, specially to manipulate some common data types. 

An important characteristic, depicted in Figure 1 , is the way 
the modules comnuini..i:e Between each pair ot communicating 
modules (or groups) is an appropriate interface, lor instance, the 
user communicates with the program front-end through the user 



interface. Each interface can usually be described by a well- 
defined, limited set of function calls (with applicable parameters) 
and data types. This is the case of all the interlaces in Figure 1 , 
except for the user interface, that is obviously described instead 
by a very complex collection of commands, options, procedures, 
and even the input and output devices involved. 

A question that is naturally raised is how Joes one extend 
the abilities of this rav tracer, particularly how does one add a 
new primitive? This is a very important question indeed, since 
after Ihe ray tracer is relatively stable, the most frequent modifi- 
cations made on it will be to add support for new primitives. It is 
desirable thai this operation is simple enough that even someone 
who is not completely acquainted with the program i- able to do 
it, ideally minimizing or even removing the need to modify the 
program itself. Well, this is ihe subject of the next section. 



Object Orientation Prelude 

If you have been programming for a while — in fact, even if 
vou haven't — certainly the words "object oriented" mean some- 
thing lo you (maybe "yes, they mean something 1 don't under- 
stand"!). "Object oriented" is definitely one of the most fashion- 
able terms in computer science nowadays — we have object- 
oriented languages, compilers, operating systems, databases, 
user interfaces, and even ray tracers. If you say your program or 
product is "object oriented," people look at you differently, 
respectfully (even if the word does not express much to them) 
Well, what does all this object orientation stuff mean, anyway? A 
complete answer is not easy, but what most people imply when 
they sav something is object oriented, is that it is well structured, 
divided in modules, and encapsulated (didn't help much,did it?). 

As you are probably aware, modularization and structures 
are two of the classical tools that a programmer has in order to 
make his program more manageable. By dividing the program in 
small routines, each with its own well defined purpose, one can 
write big (and also small) programs that tend lo become easier to 
fix and maintain. If you have ever written a medium-sized 
program in iheearly microcomputer BASIC'S— eitherC-M. Atari. 
TRS-80 or Apple — you surely know what 1 am talking about. 
Most modern languages support an additional level of 
modularization, by allowing you to group related functions m a 
single module. Trie parts of a module that are visible outside 
make up the module interface, i.e., the entry points thai can be 
called from outside. Structures allow you lo collect related data in 
a --ingle place, building more complex data types from simpler 
ones. 
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Figure One How !he modules communicate 
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We can take the C language as ,1 convenient example. In C, 
(unctions and variables can be grouped in files, and any functions 
or global variables preceded by the keyword static are not visible 
outside of the source file thev are in. Usual! v. the protois pes of the 
externally visible functions (defining the name of the function, its 
return value, and the parameter types and their order), as well as 
the data types handled by the functions in that module are 
defined in a header file (name ending in ".h"). 

Typically, a structure is used to define a complex data type, 
thai will be manipulated using a set of functions. You can think 
Of a list, defined by a simple structure and manipulated by the 
routines addtail, addhead, removehead and removetail, for in- 
stance. So, it is relatively clear that there exists a relationship 
between the data type and the functions able to manipulate it. It 
would be nice to have an extra level of grouping that allowed us 
to define a data type completely, in a single place, including both 
the data structureand the functions that understand and manipu- 
late it Ideally, only the functions in the definition of the type 
would be able to read or modify the data structure fields di- 
rectly everyone else would have to call these functions todo II 
This would allow the real data structure organization to change 
at will— as long as the manipulation functions are modified 
accordingly— without the callers ever noticing it. Well, programs 
that use this extra level of modularization are usually called 
object-oriented programs 

1 have purposefully avoided the use of the object-orienta- 
tion jargon, so that uninitiated readers could understand the 
preceding discussion. The data types defined by a module with 
an internal data structure and some manipulation functions are 
generally called objects. The manipulation functions are called 
methods. The methods and the data type define in fact an object 
class, and each individual object belonging to that class is called 
an object instance. For example, the object class BALL might 
define objects that can, according to some kind of semantics, roll, 
stop, or kick (the three methods that can be applied to BALLS). 
Both a small red ball and a big blue ball are distinct instances of 
BALL, and both can be rolled, stopped, or kicked using the same 
methods defined by the BALL class 

There are additional concepts that are important to achieve 
the exceptional level of encapsulation that truly object-oriented 
programs have, most of which are tricky to implement using a 
language that is not object oriented (like C). Probably the most 
important of them is inheritance, the ability of one class of objects 
to inherit properties of another class. This allows one class that is 
a particularization of another to use all the methods that were 
defined for the more general one. A good example is a class 
SHAPE, with the methods rotate, translate, and scale, and sub- 



classes that inherit the properties of a SHAPE: CIRCLE and 
SQUARE. Thus, besides using the methods particular to the 
CIRCLE class ( set radius, for instance), it is also possible to apply 
.i translation, for instance, to an object of the class CIRCLE —after 
all, CIRCLES are SHAPEs, aren't they? 

Practical Object Orientation 

As you can notice by the previous example, object-oriented 
techniques are particularly suitable to describe graphical objects, 
and that is precisely what a ray tracer needs to do. A ray tracer 
manipulates graphic primitives, like spheres and polygons, to 
which standard methods like intercept and normal areapplied to 
obtain the necessan. information to render a picture. Each kind of 
primitive has some very specific attributes, mainly related to its 
geometric shape, besides those that are common to all primitives 
(like color and surface properties). This is a typical case of 
inheritance: each kind of primitive is a class that inherits the 
attributes and methods of a general OBJECT class. 

You should be convinced by now that using object-oriented 
techniques to write a ray tracer seems like a good idea. A fully 
object-oriented language would be the natural way to go, but is it 
really required? Truly object-oriented languages are sometimes 
too different from what you are used to, introduce some ineffi- 
ciencies and are not widely available. Hmmm ... would it be 
possible to implement some of the nice object-oriented ideas 
using the language of choice of nine in 10 Amiga programmers? 
With some restrictions, the answer is yes. 

Since C is not an object-oriented language, there is a slight 
overhead in using object-oriented techniques in a program. Due 
to this small inconvenience, the only place where object orienta- 
tion is used in "ray" is in the object interface, where it is successful 
enough to make this overhead negligible — Y°u will notice why. 
So, "ray" is not a fully object-oriented program, just likeC is not 
really an object-oriented language. 

In ray" there is a general class, called Object, that allows 
every kind of primitive to be treated similarly. The ray tracer 
kernel, for instance, deals only with Objects— it simply does not 
know what kind of Object it is really rendering. This class sup- 
ports all the methods necessary for a primitive to be ray traced, 
although each particular kind extends an Object with attributes 
particular toils geometry. AnObject in "ray" is defined in object.h 
as: 

typ«def et i 

' jde o_nodej 
, o o_type; 
i o_eolori 
luai 
it* j 

where objtype is an enumerated type that lists all the 
possible subclasses of Object: 



-Y. 
■ 
OBJ_S*UXBEH I- 



number of defined object 



An Object thus contains: a node sub-structure to allow the 
object to be linked to a list; an identifier of which type of object this 
ms(. mv .v is; the color of this object; the illumination characteristics 
of the surface of this object; and finally, a generic pointer to data 
particular to the type of this object. You should notice that fields 
in this structure, like color and illumination characteristics, are 
attributes that every primitive, regardless of its particular type. 
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will inherit. The extension to the Object class is made through the 
o_data generic pointer, to which each primitive can link any 
special data it might need. For instance, in sphere.c the Sphere 
type is defined as (basic types like real and Point are defined in 

global.!.): 

typedef itruct t 
Point a_center; 
real 9_radiiiB; 
) Sphere; 

When a sphere is created, an Object and a Sphere structure 
are allocated and initialized, and a pointer to the Sphere is placed 
in the o_data field of the Object. No one — except the methods 
defined in sphere.c - knows what is stored in theo_data field, i.e., 
no one knows that it points to a structure made up by a Point and 
a real. This is information hiding: if, for any reasons, it is necessary 
to change the Sphere structure, no one — except the methods 
defined in sphere.c— will need to change. 

This is how the attributes of the Object class and its sub- 
classes are stored, and how inheritance works in "ray." More 
important than that is how it is possible to have a consistent, 
essentially primitive-independent way of accessing the crucial 
characteristics of an object to be ray traced. 

Attribute Manipulation 

When an object is created, the fields in the Object structure, 
and specially the data pointed to by the o_data field, are initial- 
ized with default values. Since the value of these fields is what 
effectively distinguishes two instances of a given class, there 
must be a way to modify and retrieve them. Instances of the 
Sphere class, for instance, are always created with center at the 
origin, a radius of 1 and a diffuse white, non-reflective, non- 
refractive surface. 

It was mentioned that only the methods in the subclass 
implementation know what is stored in the o_data field, and so, 
only a method in the subclass can possibly modify these at- 
tributes. Also, since there is no limit on the number of primitives 
implemented nor in the number of attributes they support, the 
process used to modify attributes must not depend on these. 

We want the user to be able to modify the attributes of an 
object in a controlled way, still keeping him unaware of what is 
effectively stored in the structures. If, for any reasons, we need to 
radically change the format or kind of data that is stored in the 
object, we would like to be able to have the opportunity to map 
user requests in the old format to the new one, and also hide the 
internal fields that are meaningless to the user. 

The obvious solution that meets most of the above criteria 
is a pair of methods.aHrsf t and attrgel, that are used to set and get 
the values of attributes. The attribute that is to be read or modified 
must be identified by a code, and this code is given by the 
enumerated type attribute, defined in attributes.h as: 



typed© f enum ( 

*tth_ehd. 
• include "coeaaon.atr" 

ATTR_CUSTOM, 
■include 'sphere. ati* 
■ i nc 1 ude 'plane . at r * 
•include 'sky.atr' 

ATTB.DUMHY 
1 attribute; 



Asis relatively obvious, this definition is not self-contained, 
since most of it is included from external files. This is done to 
make the addition of new primitives easier, reducing the number 
of modifications required in attributes.h toone. A file like sphere.a tr 
looks like (stuff deleted): 

ATT!t_UST_BEGlN 

SPHERE.CENTER . ATTP_CUSTOH. 

SPHEBE.RADIUS. 

SPHEBE_NUHATTB 

ATTR_L1ST.EHD 

where ATTR_LIST_BEG]NandATTR_LIST_ENDaremac- 
ros defined in attributes.h. The attributes common to all primi- 
tives are defined in common.atr. 

Note that the first custom attribute of each primitive is 
initialized to be ATTR_CUSTOM. This technique results in a 
unique integer code for each attribute applicable to a given 
primitive, but custom attribute identifiers of different kinds of 
primitive may (and in fact they will) be equal, as is shown in 
Figure 2. Note also that the last attribute of each primitive is 
usually primirive_NUMATTR, and this will be exactly the num- 
ber of useful attributes for that primitive. In a Sphere, for instance, 
there are six attributes that can be used (SPHERE NUMATTR = 
6): ATTR END, ATTR COLOR, ATTR.TEXTURE, 
ATTR JLLUM, SPHERE_CENTER and SPHERE_RADIUS. 

A question that is still remaining is how we will be able to 
define a function to set an attribute of an object, if the type of the 
attribute is not known. A good solution is to use the ANSI C 
variable arguments- passing facility. 

Variable Arguments 

One of the best known functions in the C standard library 
is printfQ. There is something special about printf, besides the 
frequency that it is used in normal C programs: the fact that a 
variable number of arguments can be passed toil. If you have ever 
tried to write a printf-like function, you might have stumbled on 
a shortcoming of many programming languages: most of them 
do not give you the means to write functions or create modules 
that work just like the standard library ones do. There is simply 
no way, in standard Pascal (is there really a standard?), for 
instance, to write a function that can receive a variable number of 
arguments (like Write() and ReadQ do) or an argument of any 
type (like New() does). This kind of contradiction prevents the 
use of the language in question to write its own standard library 
(forcing the use of another language, usually assembly), reduces 
the portability of the language implementation and frustrates 
programmers trying to write code that looks like the standard 
they are used to. 

One of the nicest — and also one of the least used — features 
standardized by the ANSI C committee is the variable argument- 
passing feature. It allows a routine to receive any number of 
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parameters of any lype, just like prinlf does, and to retrieve the 
parameters from the stack in a standard way. independent of the 
particular machine architecture. This feature is implemented asa 
single type and three macros, defined in the include file stdarg.h: 

void /a.list ii 

■ 

I b use it, you must declare a variable of type vajisl, that is 
used to keep track of which parameter we are currently in. It is 
initialized by a call to \ a start, that receives the last fixed param- 
eter in ihe (unction. A call to va_end must be made after the 
arguments have been used, in the same function that called Ihe 
corresponding va start. To retrieve the current parameter and 
advance to the next, va_arg should be used. It receives the r\peol 
the parameter expected, and returns its value. 

The best way to understand this feature is with a simple 
example: 



■ max int im of 

int maxint unt . 

■ 



' 






U 



. ; 



i.atg largs. intjj 



There must be at least one fixed argument to initialize the 
vajist, and the argument list in the prototype of the function 
must be terminated by "..." to indicate that there is an unknown 
number of arguments following. It is very important to keep in 
mind that there is no way to know how many arguments, and of 
which type, were really passed to your function, so you must 
provide an alternate way to get this information, either implicit or 
explicit. In the function above, the type of the arguments is 
implicitly assumed to be integer, but the number of them must be 
explicitly marked by the user by terminating the argument list 
with a zero: 

• ■ • . * 

I* WPG.NC ! "/ 

In printf(), the number and type of the arguments must be 
explicitly listed in the format string, telling the function the type 
of each parameter, and the order they arc received The o'nlv 
problem with this explicit user cooperation is that sometimes he/ 
she might write a format string that is incompatible with the 
number or type of the arguments really passed, and ... POOF!— 
the program doesn't work any more, usually with the most 
bizarre effects. 

I hese strange reactions from 'hv compute! RN doe to the 
waj variable arguments are implemented in usual computer 
architectures. Arguments are passed in the slack — roughly, a 
memory area that grows either toward increasing or decreasing 
addresses — one next to the other. A vajist variable is simply a 
pointer to a place in that area, which va_arg moves by an amount 
that is tin- size of the argument retrieved by it, so that it will be 



always pointing to the next argument. If, for any reason, the type 
of the argument passed to va_arg is wrong or the arguments have 
just ended {and the function doesn't know), vajist will be point- 
ing to the wrong place, usually an address that stores just gar- 
bage, and the values returned from subsequent calls to va_arg 
will be plain nonsense. You can imagine the rest. 

You might have already guessed how variable arguments 
can be used to implement the attrset and attrget methods. To set 
an attribute, for instance, the method has to know which object is 
to be modified, which attribute will be changed, and the new 
value of the attribute. Only the type of the latter can vary, 
depending on which attribute is being changed. Thus, somehow 
there must be a way to associate each attribute identifier to its 
type, so that the method will know which type to remove from the 
stack. This connection is made through an array of types indexed 
by the attribute identifier, that will be present in each primitive. 
The possible types, defined in attributes.!*, are: 



typedet mum 
TYPE_INT, 
TYPE_REAL. 
TYPE_PTR, 
TYPE_VOID 

) ettrtype; 



• 



integer argument •/ 

real argument 
pointer (address) •/ 
unused argumen> 



The type array for the sphere is (from sphere.c): 

internal attrtype stypestSPHEP£_NVKATTP| » ( 
TYPE_VOID. /• Alwayo begin with TYPE_VOID •/ 



attribute! 



TYPE_PTR. 
TYPE_PTR. 
rvi r_r::~. 



/■ ATTR.COWR (Color -| 

>• ATTR_TEXTURE (Texture •) 

'• ATTP_1LUW (Ilium "I 






• Private attributes 

• 

TYPE.PTR. /' SPHEPE_CEHTER (Point -I 

TVPE_REAL /• SPHEPE_PADIUS 



You should note that therearesix items in this array, one for 
each of the six attributes that are valid for Spheres, and that they 
are ordered just like in Figure 2. 

Since we are using variable arguments, the attrset and 
attrget methods can be designed so that they set or get more than 
one attribute at a time. This is easily done by defining the 
functions according to the following prototypes: 



int attrset (Object *ob) . 
int attrget [Object 'obj. 



...I 
. . .) 



Following the object to be manipulated there is a list of 
attributes and their values, terminated by an ATTR_END, for 
example: 



Color L.O, 1.0. I .01 j 

attrset (sph. 

SPHERE.RADIUS. 2.5. 

ATTR..C0LOR. Iwhite. 
ATTP^EMDl { 



In the case of the attrget method, the arguments are pointers 
to the variables in which the value of the attributes will be stored; 



Color color; 
real r; 
attrget (sph. 

SPHER E.RADIUS, ir. 

A7TR_COLOR. icolot. 
ATTP_END» ; 



ACS TECH 1 " 



L<K»kinj» .it the array wiih the types for the sphere, you can 
determine the type oi tin- value thai goes after each one »i the 
attributes, e g . after a SPI H Ki RADII S there must be a real an 
ATTR_COLOR must be followed by .1 Color pointer, and so on. 
Don't forget that in the case ol attrgel all values are pointers, in 
such .1 way that values can be returned m the area pointed to by 
them. To better understand this, you may associate attrset and 
attrgel to print! and scanf, respectively. 

Methodology 

A> already mentioned, the two fundamental methods that 
the Object class musl implement are intercept and normal. Both 
of them depend entire!) on the kind of object in question: the 
Objectdasssunpl) doesn't know rtowtocalculateaninterceptjon 
el .1 normal without knowing thai the object is in tact a sphere or 
a plane, for Instance, and this will be the case ot most methods in 
this ray tracer (well, currently all of them). So, to implement this, 
the intercept method in the Object class could have been written 
as something like: 



sphere_prop that is globally visible, and it contains pointers to the 
functions that implement those methods, winch are rtol directly 
visible outside, From sphere.i (stutl deleted): 



■no nut. 



■ 






' 



' 



' 












There are. however, better wavs to implement the above, 
thai Will group all the information related to each kind of primi- 
tive in a single place, instead of scattering it through many parts 
ol the program Each SUbcla96 declares all the properties it sup- 
ports 111 a structure that is the onlv thing visible outside ol thai 
subclass implementa turn I hisstructureisdelined in properties h 
as: 



voia ' 

■ 



■ 



■ 



■ 



The above structure declaration is the kind Ol thing that 
really shocks v neophytes well, admittedly, even seasoned 

programmers need to take a deep breath before trying to write 
such a thing. A rough translation: each of the hrst seven lines 
declare a pointer to a (unction, to Code that can be executed. The 
fifth line, tor instance, declares ,1 field named op_intercept that 
points to a function that accepts two parameters, an Object 
pointer and a 1. me pointer, and returnsa real. A call to one of these 
functions using the pointer looks like 



■ 



* 



• 

In essence, each of the function pointers in the Properties 
structure is a method, and each primitive declares .1 Properties 
structure where each field is filled with the appropriated function 
that implements that method for that primitive In the sphere 
class, for instance, there is ,1 Properties structure named 



In this way, all the information on the methods tor each 
primitive are grouped together, and easily accessible by the 
Object class. Better yet. the Objed class ^w\ have an an.u ol 
Properties directk indexed by the type ol the object, like in 
object. c: 



exivrn 



■ 

■ 
fcsphpr«_prop. 
t«,ky_i ; ' OBJ.i 

fcpUn»_ptop /• OBJ_i'' ' 

This allows the intercept method of the Object class shown 

berore to be rewritten m a more concise way, thai is also much 
more efficient and independent of the currently implemented 
primitive types: 

* 
■ 

Obviously* the methods pointed to bj the fields in the 

Properties structure are in the code ot the primitive in question. 

so thej know everything about it, including its geometry and 
what kind of information is stored m the o_data field. 

I el s get back to the definition ot the Properties structure. 
There is one last field that was not yet mentioned, op_attrtv pe It 
is simply a pointer to an array ot attribute types, exactly like the 

one shown in the Variable Arguments sec turn You might still be 
wondering what each of those methods in the structure does, and 
why they are there. The methods .ire 
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op_create used lo create an instance of a primitive of a 

particular type (allocales memory and initializes it). 
op_destroy simpty destroys a given instance of a pnmilive. 

freeing Ihe memory used. 
op_normal returns Ihe normal of a primitive at a given point 

(assumed to lie on the surface of the pnmitive). 
op.color returns the color of an object at a given point (also 

assumed to lie on the surface), 
opjnlercept returns the interception of a given line, in parametnc 

form, with an object 
op_attrset sets each of the requested attnbutes of the object to 

the corresponding value given. 
op_attrget returns the value of each of the requested attnbutes 

in the corresponding value pointer. 



Each of the above has a corresponding method imple- 
mented in the Object class, like the intercept method already 
shown. If you look carefully in object.c, you will notice that all of 
the methods implemented there simply forward the requests to 
the appropriate subclasses that know how to handle them. You 
might be thinking what may be gained by introducing functions 
that do essentially nothing. I.ook at the following piece of code: 

Object 'sphere, 'plane; 

extern Line -ray; • Initialised elsewhere V 

real tp. t«i 

sphere ■ create (08J_SPHEFE) : 
plane = create (OBJ_PLA.\< 

tp • intercept (plane, ray); 
ta ■ intercept (sphere. 
if (tp < to) 

print* cplane la nearer- i; 
else 

print! ("aphore is nearer-); 

destroy (plane); 
destroy Ispherel; 

It may look surprising, but the code above does work in 
"ray," actually as a result of the object orientation techniques just 
described. 

The Ray Tracer Kernel 

The ray tracer itself is quite simple, and it is completely 
contained in the file ray.c. It is basically the algorithm presented 
in the last issue, with additional functions tocompute the Whitted 
illumination model (locaI()), the reflection contribution (reflect 
0), the transmission contribution (transmit ()) and the shadows 
(obscured ()>. A single ray is recursively traced by raytraceO and 
illuminate(), and raydispatch() traces all the rays in a picture, 
sending the results to the device driver through the routines 
picture.c. 

You will notice that the main() function in ray.c calls two 
world manipulation functions, wbuild() and wdestroy(). These 
functions are in input.c and are used to build a world (containing 
all the features of the scene, including the objects and the lamps) 
from a ray scene description input file. If you look carefully at the 
code in input.c, you might observe that it depends not only on the 
types of primitives currently implemented, but also on the at- 
tributes they support. But wait! Isn't this exactly the kind of thing 
we were trying to avoid by using object orientation? Er ... yes, but 
you'll see why. 

In this case, there were essentially three alternatives. The 
first is the one currently implemented, where the knowledge of 
the primitive types and their attributes is not completely con- 
tained in the primitive implementation, making the addition of 
other primitives somewhat harder. 



The second one would be to createan additional method for 
every primitive, that would read its parameters from a given file. 
In this way, the wbuild() routine, instead of reading each of the 
values and passing them to the primitive, would send the entire 
line to be processed by the primitive. Unfortunately, this method 
would make the primitives dependent on the kind of modeling 
interface in use (scene description file), and would make it 
impractical to change the program to run under an Intuition 
interface, for instance. 

The third one would be to simply ignore input.c and use the 
routines create)), destroy!), attrset(),'attrgetO and raytrace() to 
model and render scenes directly. This is by far the cleaner and 
simpler solution, but it introduces the drawback of needing 
recompilation every time the scene is changed. Also, one execut- 
able is needed for each scene, and, unless "ray" is made into a 
shared library, the code for the ray tracer and the primitives will 
be duplicated in each executable. 

The initial idea was to support the programmatic interface 
to model scenes, but it became somewhat awkward to use. The 
scene description file was then created to provide an easier and 
faster way to model scenes. With few changes, it is still possible 
to use the programmatic interface, simply by discarding input.c 
and writing two substitute routines wbuildf) to create all the 
necessary objects, and wdcstroyO to destroy them. It may also be 
possible, if carefully planned, to use the second solution in a way 
that is less dependent on the kind of interface, mavbe creating a 
method that maps a string to an integer ID (the string 
"ATTR_COLOR" would be mapped to the number 
ATTR_COLOR). 

Food for Thought 

The alternatives above and the idea of changing the inter- 
face used to access "ray" create interesting possibilities of an 
interactive version of the program or a ray tracing shared library 
Although texturesarenot implemented, theco!orat() routine was 
designed specifically to support solid textures easily. Refraction 
is not implemented, but the rest of the program is prepared to 
handle it, and the basic theory was explained in the previous 
issue. There are various illumination models out there, which 
create truly realistic effects. Ray tracing time can be substantially 
reducedby many existingacceleration techniques. New primitives 
can be added easily (step-by-step procedure explained in 
lemplate.c). and this fact alone can be the source of hours of 
entertainment (and debugging!). 

In brief, there are lots of things to be done. If you have the 
time and the will to explore this package. I hope that you learn 
about computer graphics and programming in general as much 
as I did. If you want to delve into more advanced algorithms, try 
the bibliography listed in the last issue, and if you have any 
problems with this implementation, you may try to reach me on 
Internet as bruno@brlncc.bitnet or through AC's TECH. I hope 
you have fun! 
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Disk Access 

Made Easy! 



by Dan Babcock 



Floppy drive access is usually performed via the 

trackdisk device module of the Operating system. Ttackdisk pro- 
vides the same consistent, high-level Interface as other device drivers 
in the system, and has been optimized internally for speed Given 
lhst,tnen?fcusuallv no reason not to use trackdisk when multitasking 
normally. Special non-multitasking applications must, however, re- 
sort to programming the hardware directly. The purpose of this 
article is topreaent a set of easy-to-use routines for performing floppy 
access without the aid of the operating system. 

Using the Routines 

The disk I/O package (Listing 2) consists of six major 
routines: Read, Write. MotorOft. Inquire. SeekZero, and 

Restore) (eadPosit ion. Read and Write perform the actual disk opera- 
tions MotorOff turns off all drive motors (Read and Write automati- 
cally* turn them on), and deselects all drives Inquire tells you what 
drives arc present in the system. Seek/ero sends all drives to track 
zero, placing the drives al I known position so that seek operations 
are performed correctly, while recording the previous track location 
of the drives m the DlSK_OldTrack field of the DISK. Data Area 
global data area. Seek/ero also does the favor of setting up the 
relevant CIA data direction registers. Restorelleadl'osition steps the 
heads ti> the DISK_01dTrack tracks, previously recorded by SeekZero. 
The register inputs and outputs of these routines are summarized 
below Note that there are absolutely no restrictions on any of the 
parameters; for exjmple, the buffer pointer may point to an odd 
address in fast RAM 



Inputs 

DO.L - length (bytes) 

01 .L - offset from slart of d.sk (bytes) 

D2.L - drive (0-3) 

AOL - pointer to user buffer 
Output 

D7.L - error code (zero K no error) 



Inputs 

DO.L - length (bytes) 

01 ,L - offsef from start of disk (bytes) 

02 L - dnve (0-3) 

AO.L - pointer to user buffer 
NOTE: The wnte routine offers a verify option that may be enabled by 
changing the VERIFYFLAG constant near the beginning of the listing. 

Output 

D7.L • error code (zero if no error) 



Inquire 



Output 

DO.L • dnve map 
•example: 5 (0101) means dnve and 2 are present. 



Other Routines— 



MotorOH: 

SeekZero: 

BestoreHeadPosition: 

No Inputs or Outputs 

Some set-up work is required before these routines may be 
called. The DISK RawBuffor and DISK.DecodedBufier fields of 
DlSK_DataArea must be set to point to free memory areas of size 
14,716 bytes and 5,632 b) tes. respectively. The DISK_CurrentTrack 
entries must agree with the physical position oleach drive; you must 
call SeekZero or otherwise assure that that's the case. You should 
normally also call Inquire to find out what drives are installed. After 
completing this set-up. Read and Write may be called freely to 
perform theactualjob. Read and Wnte make few assumptions about 
the state of the machine, and take care not to drastically alter it. This 
permits use in a wide variety of "hostile" environments 

Drive Specifications 

Almost everv veteran Amiga user has experienced the 
frustration of aprognun (usually a game) absolutely refusing to load. 
When it comes to disk drives, playing fast and loose with the 
manufacturer's specifications .ilmost assures that your program will 
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fail lo work properly on someone's machine. For your convenience, 
Ihe most critical specifications a re listed in Table 1 . In addition to head 
stepping considerations, take into account variations in drive speed, 
which appear at the programmer level as a variation in track length. 
Write a gap of 1.660 byles to ensure that the track is completely- 
erased, and plan for the gap to be that large when reading. That 

translates toa read si/e of I4,7t6byles and a write size of 13,628 bytes. 
The read size is one sector (1088 raw bytes) larger to ensure that 1 1 
complete sectors are read. These numbers are used by trackdisk (and 
these routines), and your application will work just as reliably as 
trackdisk if you use them too. 



Table One 


Step rate 


-3ms' 


Settle time 


15ms 


Post-write delay 


2ms 


Side select delay 


1ms 



"4ms when looking lor track zero 

Inside the Routines - 

Some key facts about the internal workings of the disk 
routines will be mentioned here. First, the blitter is not used for 
encoding or decoding. Using the blitter would speed things up, but 
would make the routines less general purpose. As it is, decoding a 
track takes about 16 milliseconds, and encoding a track takes about 
68 milliseconds (on a 68000/68010 Amiga). The decoding time is 
hardly noticeable, but the encoding lime makes writing seem a bit 
sluggish. Secondly, the CIA timers are not used to implement the 
necessary delays; rather, the delay is based on counting a certain 
number of horizontal scan lines, at approximately 63 microseconds 
each. This approach leaves the timers completely free for other 
concurrent uses. As you can see, the design of the routines facilitates 
a simple drop-in inclusion into almost any program, requiring very 
little external support. 

Taking Over Gracefully 

For testing these routines in a normal (multitasking) envi- 
ronment, it is desireable to take over floppy control functions from 
the operating system. The OS-friendly method of doing so is to call 
DR_GETUNIT in disk. resource. Once permission has been obtained, 
our routines may directly access the disk hardware without fear of 
interferencefromtheoperatingsvMem l >Iauirse. normal multitasking 
rules must still be obeyed. Listing 1 shows a program that demon- 
strates calling DR_CETL'MT before making use of the low level disk 
I/O routines, and cleaning up afterwards. 

This is Not the End- 

The disk routinesarenot presented with the intent to be the 
"last word" on disk routines. Rather, they are a very useful starting 
point; you don't have to reinvent the wheel. You are encouraged to 
make your own special improvements, of course and, we hope, share 
the result with everyone. I've already incorporated the disk routines 
successfully into VBRMon (see last issue's article), and no doubt you 
will find your own applications. 



Recommended Reading - 

Vie Hardware Reference Manual is the official guide to pro- 
gramming the hardware, and should always be consulted first. The 
standard Amiga disk format isdocumented in the Rom Kernel Manual: 
Libraries and Devices. 1 found Abacus's Amiga Disk Drives Inside and 
Out to be quite helpful, though it contains many errors. Lastly, 
Randell Jesup's "More on Low-Level Disk Access," published in 
Commodore's AmigaMail, contains many very helpful tips. 

About the Author 

Dan Babcock is an electric*] engineering major at Pennsyl- 
vania State University and an avid assembly programmer. Contact 
him via Internet as d6b@ecl.psu.edu. 



Listing One disks 



idisk.i Package tor readiofl'-riting the standard trackdln forwt 
■ ftlt the OS 

jCopyiiaht icl 1991 by Din Bibcock 

.•Access -he routine* u follow: 
.■for iPi 



I 
■ 
buffer 

;fcoullna nase; Wiii» 
;Ssm pareaeters as above. 

;WTE: Error cod* r«uro-d id DLL - if ok, tin 



.■General errors 

. ; >.'".! :ii:v-'.i: 

;Besd error* 

: Sync 
□ISK_BadHeader 

DISK_6*dajta 



•qu 



■qu 
•qa 

an 



:rori 
DISKjiritePiotected equ 
DISK_V«n(yErr« equ 



.■AdtJitiw-ai routines: 

.-HotorQft - Turn oft all drive sotois 

.-Inquire - Find out -hat drives are in the ryita* 

Da drive sip in DO 
;5eekZero - Send all drives co track wo 
; Bettor eMMdFos it ion - step driww to previous (before SetkZerol positli 



vsiirrOH 



- Ueer-Mttable parameters 

equ 1 ;0ir. . 



dskpt 



ira 

eqa 
BBC 



dakpeh 



iClobal data structure 



clrso 

■ 

DISK.DewdedBufter 

DlS*L01dTracV 

DISK_3ire 



so.b 
eo.l 

so.: 

so.b 
soval 



■MCJ 



'di*K. binary" 
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bt*.w 
bra." 
bra.w 

bin 



joffael D 
Hilt* iOltttt 4 

IfctorOtt ;c: 
Inquire 
Seek?*: . 
teat irsHMdl ■ .■ 






DlSK_DaieArea: 

dcb.b 
dc.l 

dc.l 
dcb.fa 



1 

g 



: -.el 2* 
iRevflUl 



iVKt; Ttin u a public value, 
DISXJttwBufSiie equ 



[o r* changed 1 



■ 


<-,- 




CldOPH 


•go 


S10I 


ciabddrb 


■'■■ 


SJOO 


ciaaddra 


■T.. 


S1101 



(■port ant d;ak parar«ter». »ut»ary: 

D 1*01. ng for track zero. 



Step rate: )na. 1m <Ai 
Settle tiae: 1S« 
Post -write delay; 2&b 
Side aelect dc 



Read! 




■OVM.I 


dO-dS/eO 


im ; 


•O.dl 


1*4 


DISX_£lat*Xrealpc).e* 


■ove.l 


l_cuKoa,a4 


■ove.l 


iciabprb.at 


■Ort.l 


dl.di 


add.' 


00. d) 


op.l 


H0113O.d3 


bbi.l 


.Erm ;go it * 


bar.b 


Select Drive 


aove.l 


■fl.al 


■ove.l 


dO.di 


:The ml of the re*d raw 


laadtom: 




■JVW.l 


dl.dl 


diva.* 


■Ill.dl idJ.u li ' 


aove.l 


d),dl 


clr.w 


dl 


IWp 


dl idi :■ byte OlfMI 


bjr.b 


Seek 


bit 


ReedTr ackAndOecode 


cst.l 


d7 


bne.i 


.End 


BOVt.t 


DtSILPKodtdl ' ■ * 


add.w 


d»,aC 


Hb.H 


■ 'SUl.tM 


ntg.w 


ji 


add.l 


dl.dl 



'.jnber of bytei that could be trarnfened fn 
:D5.L • nuabei of by tea left in the entire Feed .'*■!"* 



OV.l 


dS.dl 


been 


.finuhup :>■ 


tab. 1 


d4.d5 


■ove.l 




Mr 


■ ,v. 


•dd.l 


dO.al 


bra. a 


■»■**« 



FimthUp 


■ove.l 




- ..,-;'. 


Mi 


';>■*■■ 










aovea.l 


Mpl-.d 




rti 






■ovtq 
bra. a 


1 
.End 



bytei Li 






■ 

isber in c; I 
.Exits in SOOns if diak ready doein't yet set 





■avca.l 






1 ;:; - 


D.dl 




or.b 


■ ■ 




bclr 


tl, lali ;Botor on 




bclr 


-i 






.. 


cap b 


• ; check dl 








Deq.i 


.13 




ibri 


dO.. LI 


'■'■ h 








OOVee.l 


iepi..dO/dJ 




rti 





a.b 



if either the 
be* or the deitination u 





■OVfS, . 






-;..: 


nu.d) 




bec* 


Error 












. let to 'jpc* 1 








baei 


. set to lower 










■ove.b 


■ 






1 




■ IV. fe 


dJ.DISR.CurrentTrack(a^.dJ.-l 






il.dJ 




baet 


11,1**1 if*l ■ lower trackil 






dl.dO 




beq.a 


.SideSeleetCnly 



.Steplm 






del ay 1: 



bhi.a 
bclr 

neg.b 

Me' 

aubq.b 

brw.s 

btr.b 



Mr.b 
bra.s 



■Ove - 
; ; .i - 



aove.l 
MVtq 
bra. i 



■1,1**1 

dO 

I 



tl.du 



"<st itu*. ion 



Bud 



■ 



delay: 
.End 



l 
.Error 



dO. -tip! 
I 

delay 
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*: ±yt : 



d*l*yli: 



'I...,:. 



xvc. 1 

■ovtq 

bia.i 

■ovp.l 

0OV«.W 



■ 

delay 

1 



;£n-*i wicr. M91C dflay nusbet 





push 


dl 




■ove.b 


vhpos: 




CBp.t 


. . : 




dbn 






;* ; 






; op 


dC 




tM 





SitMgi 



r^vr 1 



- .- . 
Itl 



■ 



1 






;clear syrtf<donc 



ScanSynci 



•Sync: 



toundi 



■ 



poi! 


•4 


nve.l 


::*»_*..-- 


idd.v 


1 


c«e.«* 


■ 


btq.i 




cap.L 


•2.a4 


Wll.S 




ro.r- 


1 


PCP 


•4 


'• 




op.w 


■ 


bne.a 


• 


nUq.i 




bra.i 


.found 


-i 


U 


H - 





Hn«Md3 

:P«lorc 4 :«. tricK rnd 

- 





tar.b 


Seiftegi 




sove.H 


1 


p»l 1 ■ V 


BOVe.B 


_ iSKsr. 








■ 








mat, . 






■m.n 


• 




■ove.b 


■ 




Mat 


1 




tae.i 






rop.b 






t*j.« 












«nrtq 






■ ! - 








.UotTlOV 



I rt Hi..--.- 



Kvcq 


■ 




. 












■ 




litlQ- .' 


aovt.w 


1 


:cl««r . 


. < - . 






it 1 



















*»■*.: 


















Oa -■ 




WOf.t 




■ove.l 


iSl.-J 


noveq 


' 




• 


.SKLoopi 




bar 








we. a 


.tod 




D<KOd«: ■ 




■ 




1 


Ur 












bat.i 






■ 




■ 


















i0ecod« 


•ovm 


• 


"■!•: 


• 


won A 


■ 










■ove.l 




















nove.l 




















tat. a 


.CUtaEi 










•oveo. 1 


■ 


■:> • . 




- .... 












noveq 









■ 



:■■: - - 
;D0 - 1- 

BOV».. 

■ove.: 



AC'sTECH'" 



,-« Ul 






rie 



iar.l pointer to dattinaiion in *,0 - .ipUted 
:<»u» in W 



ajv*». : 


■ 


■ pom; 


10. es 


■ove.l 


KHS55* 


■OVC.l 






'. . 


Mt.b 


Encode 


■ove.l 


dl.dO 


bsr.b 


Encode 


and.l 


*5H«5»%,d* 


POVfM . 


■ 


Til 





En rode Block: 

Ji In « 



-..■ - 






ncveq 


1 


itncedi add bil 






puih 


*J 




■ovc.M 


11512/4 




KW1.I 


' 


:. . 


■ove.l 


■ - 




■ 


■ 






Encode 




libra 


■ 


.■Ebcmw * 








► ■-'!- 






aove.w 


' ■ 


- 


■ .<• . ; 


. - ■ 



Encode. 

lusea dO.dl.dl.aO - 

jkccumUtn 



in 01 



end.: 


■ 


rni.l 


dO.dJ 




<K,d2 


■ove.l 




•da.; 






' 


Met 




and.l 




beq.s 


■ 

.Oil 




' 



ik 



- - 






-'.-■ 



- V..L 

tr.e.i 



.... . . 



.BeKtClock 



but 


16. da 


Me. i 


.end 


Mel 


17. dO 


bra.s 


endl 






Hdi 



rti 



EneodeAndViiteTrack: 
; Enter with pointer to source del* in U 
Enter «i aj.«« 



nd 



EecLoopi 



nvt* . . 


da-de/aO/aJ.-tapi 




■ove.l 


DIS»_Ba-- ' 




byte* 


2 byte* for hardware Dug 




BOve.l 


ISaaaaaeaa.dl 101410... 




HVf,« 






■ove.l 


■ 




dbre 






Subq.l 


>l.a0 i rooD for ; e«ra bytea at 


the very 


■ovtq 


lll.dl ;nu*ber of lectors 




■ovaq 


10. di ;>ector COi 




■ove.l 


ISaaaaaaaa. laOl 




Mr.b 


Correct 




addq.l 


14. aO 




■ove.l 


ism*i<e«. iaO). 




■ovt.l 


ItftQOOOOO.dO 




■oveq 


1 




■ove-t 


DISK_Cut rentTrack (a - 




nap 


d* 




■ 


da.dO 




nvi . . 


di.d* 




1*1.1 


IB.dt 




Of.l 


■ ■ 




or.] 






bar 


Encode Loco. ; header 




■eve ! 


i 




~-' ■*- 


■ 




Mr 


ETiCodeLonfl :'0S recovery info* 
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The important part of this protocol is found in the Data 
strings in the SEND and RECEIVE panels. Briefly, the RECEIVE 
Data entry says to read data in lft-megabyte (SlOutXKXl-hyte) 
chunks until an SF7 is received .The SEND Data entry says to send 
Nwnegahvte chunks of data until there is none left, and then send 
SF7. {Note:SF7 is a special MIDI byte meaning "end of system 
exclusive data") 

In other words, this protocol is rather mindless. It grab-, or 
Sends as much data as ii can find, regardless of what the data 
looks like. If you could hand i la Deluxel'aint file, for example, lhi> 
protocol would happily send it to y< -ur MIDI synthesizer. (No, the 
picture would not appear on your Synth's front panel') 

What Does a Smart Protocol Seed to Know? 

In make your protocol smarter, you need to tell it some Vital 
information, such as; 

• How long (in byles) is Ihe data lor 1 patch? 

• How do I ask lor a patch' 

• How do I recognize the beginning ol a legal patch? 

• Which byte represents the patch number 7 

• Where is the patch name located, and how long is it? 

• When I am sent a patch, do I need to respond 7 

• When I send a patch, should I expect an 
acknowledgement? 

• If the user aborts a transfer, should I intorm the 
instrument? 

You do not need to answer .ill of the questions: only those 
that apply to your instrument. For example, some instruments 
transmit ail their data in one big message, but others require an 
elaborate "conversation" between the sender and the recipient 
You must read vour instrument's system-exclusive documenta* 
don to determine which questions need to beanswered. For some 
help with this, see Phil Saunders' "Medley" columns in the April 
and May 1991 issues of Amazing Computing 

Building a Protocol: One Approach 

After writing several protocols. I discovered thai there is a 
partem to the process. 1 lere's a brief outline. 



L Obtain a copy of your instrument s system exclusive documenta- 
tion. Specifically, you'll need to know the proper teres to send when 
requesting a patch from the instrument, and the format of a patch 
dump itself. If this information is not included in the owner's 

manual, then contact the manufacturer. Many manufacturers will 
send you the information free of charge. 

2. Use Generic.Singlc to receitv a patch from your instrument. You 
will need to initiate tlu- patch transfer yourself by pressing the 
appropriate buttons on your instrument. 

3. If the manufacturer's documentation does not tell you the size of a 
patch dump, then look at a {Hitch's data using the Librarian's Edit 
l.ntry command, and determine tlie size yourself You may also 

h to examine the patch dump in more detail. 

4. Starting with a copy of Generic. Single, write the RECEIVE part of 
the protocol. Test it. 

5. Write the SEND part of the protocol. 

6. Make Music X extract and display the names of patches as the are 
received, if applicable. 

The rest of this article will concentr a te on items (4) through 
(6). Berore we can construct the SEND and RECEIVE parts of the 

protocol, however, we must learn about Music-X variables. There 
are three kinds: numeric, data, and string. 

Sumeric Variables 

A numeric variable is much like one found in programming 
languages or high-school algebra. It is a single letter (case-insen 

sitive) that stands for a numeric value. Some ot these variables 
may have their values sel by you on the Librarian Page: 

P The patch number that you sel on the Librarian Page. 
N The MIDI channel that you set on Ihe Librarian Page 
and others have their values maintained by Music-X: 
M Total blocks sent. 
V The last value received. 
K Checksum ot a specified sequence ol byles. 

A complete list of numeric variables is found in the manual. 

Ikila Variables 

I he twodata variables, X and Y.store sequences of data -vent 
or received by the Librarian. X stores data in its raw, unmodified 
form. Y stores data in "nibblized" form, discussed later. The 
manual discusses the formal syntax, but here are a few examples 
to get us warmed up. 

In general, to store k bytes of data, you use the expression 

<X.k> 

For example, this is how \ OU tell Music-X to send or receive 
25 ($19) bytes of data: 



(X 19) 
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Congratulations! After working hard all summer playing 
keyboards with your band, you finally have saved up enough 
money to buy that fancy WhizzySynth 3000 sitting in the music 
store. You bring it home and happily start making your own 
patches. At the end of the day, you decide to store those patches 
on an Amiga disk using your trusty Music-X Librarian. But after 
looking through your "Protocols" directory, you find that the 
Music-X Librarian doesn't support the WhizzySynth 3000 for 
patch transfers! Oh no... what can you do now? 

Well, it's time lo write your own protocol. Music-X's Librar- 
ian is billed as "universal"; it can communicate with any MIDI 
instrument, provided that you supply the right information 
using the built-in Protocol Editor. Although this process is docu- 
mented in the Music-X manual, it is still tricky to do. In addition, 
the manual is more of a reference than a tutorial 

This article will teach you how to write a Music-X protocol 
and contains plenty of examples. I won't repeat straightforward 
information found in the manual, so I recommend having it neat 
you while you work through thisarticle. Also, I won't cover every 
single detail about protocols; instead, I'll concentrate on the more 
practical uses (and a few less common ones) so you can start 
writing protocols as quickly as possible. 

Since this is a technical journal, I'll assume that you know 
how to use an ASCII table and hexadecimal numbers. In the text, 
all hex numbers will be preceded by a dollar sign to distinguish 
them from decimal numbers. (For example, hex S42 equals 66 in 
base ten.) In addition, some familiarity with MIDI system exclu- 
sive data will be helpful. 

What is a Protocol? 

First of all, what is a protocol? It is a general description of 
what your instrument's patch data looks like. (When I say "instru- 
ment " here, I really mean any MIDI device that is capable of tending and 
receivoig system exclusive data.) Equipped with this information, 
Music-X can send and receive your patch data. If the incoming 
MIDI bytes don't match the given description, then Music-X will 
inform you that an error has occurred. 

Both libraries and protocols may be saved as separate files 
on your disk. The following diagram illustrates the relationship 
of library and protocol files (see figure one). 
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Although library files .ire physically separate from protocol 
files, every library file has a COPY of some protocol inside it li 
voumotiify the copy inside a library, and then save the library, the 
protocol file on disk is not affected. Similarly, modifying the 
protocol f ileondiskdoes not affect any libraries. Thus, if you have 
a protocol that is used by ten different libraries, and you want to 
modify thai protocol, you must change it in all 10 libraries! This 
is a shortcoming of the implementation. 

Music-X comes supplied with protocols for several popular 
instruments. In pi..ticular, there is a "generic" protocol called 
Ceneric.Single that works for almost all instruments. "Well," you 
say, "it this, generic protocol is so versatile, why not use il for all 
my instruments 7 " One reason la that Ceneric.Single cannot re- 
quest patches trom your instrument— you must initiate the trans- 
fer from the instrument's front panel (assuming this is possible) 
A second reason is that it cannot distinguish legal trom illegal 
data. This means that it there is. i transmission error between your 
instrument and your Amiga, the generic protocol will not notice. 

\ lowever. Generic. Single is a. good starting point lor writ- 
ing your own specific protocol. Let's take a look at the generic 
protocol by making a generic library. Run Music-X, and choose 
Librarian from the Mode menu. Then choose New... from the File 
menu, move to the appropriate directory, and select the file 
GenericSingle. Finally, choose Modify Protocol from the Edit 
menu, and we have arrived at the Protocol Editor (set figure two): 
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Here is how you It'll Music-X to SKIP past 25 bytes of data, not 
storing it: 

(X.19.19) 

Here is how to tell Music-X to break 50 bytes of data into 
nybbles. delete all the most-signhcant nybbles, and concatenate 
the remaining data into 25 ($19) bytes: 

(Y.19) 

Siring Variables 

Siring variables can hold any tent. The most commonly 
used string vat iable is Prefix, whose value is notaled as PR in your 
data. Typically, system exclusive messages for the same instru- 
ment will begin with the same few bytes. To save typing (and 
make modification easier later), store those bytes inside the PR 
variable Our later examples will all do this 

A second, very useful string variable is the Program string, 
which is represented as PC To use it, fill in the strings labeled 
Normal Program and Preview Program with anything you like. 
The value of the PG variable will be either of these two strings. 
You toggle hetwi-en the two values hy pressing the PREVIEW 
button on the Librarian Page. This provides a convenient way for 
the user to change the behavior of the protocol without entering 
the Protocol Editor. 

Two genera I -purpose string variables are known merely as 
«1 and #2. Fill them with any data you like, and use them 
anywhere on the SEND and RECEPv*E panels. If you don't actu- 
ally need these strings for protocol data, they provide a conve- 
nient place to write comments to yourself about the protocol. 

Writing the Send and Receive Strings 

Filling in the SEND and RECEIVE panels is perhaps the 
most difficult part of protocol writing. You must describe a MIDI 
"conversation" that allows your instrument and Music-X to 
communicate. Music-X breaks down the communication into 
five types of messages: Initiate, Confirm, Ack, Data, and Cancel. 
Some instruments use only a subset of these messages, but others 
require an ongoing conversation (known as "handshaking") 
while data is being transferred (see figure three). 

An Initiate string says, "Hello, I would like to begin a patch 
transfer." To determine its value, consult your instrument's 
system exclusive documentation, and look for a message called 



Figure Three Handshaking 



"Request to send." "Request for bulk dump," or something 
similar. For the SEND Initiate string, one often uses the header 
from a patch dump. 

If your instrument does not require any handshaking, then 
you will need to useonly the Initiate and Data strings, and you are 
now ready to write your Data strings. These contain the X and/ 
or Y data variables for sending or receiving the patch data and 
storing it asa library entry. The case studies in the next sec lion will 
provide several examples. 

If you instrument does require handshaking, then you must 
also provide Confirm and/or Ack ("Acknowledge") strings. 
These strings each represent the message "1 am ready!" Confirm 
is sent by the instrument (and so Music-X must be told how to 
recognize it), and Ack is sent by Music-X. Depending on the 
system exclusive implementation, your instrument expects a 
particular sequenceof Confirm/ Data/ Ack messages. The Music- 
X manual is really quite good about explaining this mechanism; 
however, you will need to spend some time with your instrument's 
svstem exclusive documentation to figure out what messages 
need to be used. 

Finally, if vour instrument requires a special message if the 
patch transfer is aborted, you should fill a value for the Cancel 
string. 

CASE STUD)': Sequential Circuits Prophet TH synthesizer 

Sequential Circuits was the company that essentially in- 
vented MIDI. The T8 has a very simple MIDI implementation, 
and the patches haveno names, so theprotocol itself isquiteshort. 
Reading the T8 manual, we find that the following message 
will ask the T8 to send a particular patch via MIDI: 

$F0 'Begin system exclusive" byte. 

SOI Sequential Circuits' manufacturer ID. 

$00 Request to send a patch, please 

The patch number. 
SF7 "End ol system exclusive" byte. 

Music-X needs to send this message when it wants to 
receive a patch. So, we fill in the following data in the RECEIVE 
Initiate box: 

F0.01.00.P. F7 

Now. Music-X must be prepared to receive data from the 
T8. A patch contains 68 ($44) bytes of data, followed by SF7. So, 
in the RECEIVE Data box, we write: 

(X.44). F7 



miiM 




I 



jump 



lie 



1 



Now, we could have written (X.45) and grabbed the SF7 
byte at the same time. However, by writing SF7 explicitly, we 
l ausc Music-X to check that an SF7 is received as the 69th byte. 
Also, since we have specified the SF7 separately, not as part of an 
"X" variable, it will not be stored as part of the patch. We must 
remember to append an SF7 when we send our patch data back 
to the T8. 

To fill in the SEND panel, we must examine the T8 patch 
data dump format: 
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SFO 
$01 
$03 



SF7 



'Begin system exclusive" byle. 

Sequential Circuits' manufacturer ID. 

This is data (or one patch. 

The patch number. 

68 bytes ot patch data. 

"End ot system exclusive* byte. 



To transmit the patch back to the instrument, we could 
simply send everything we have stored. However, this is a bad 
solution because the original patch number is stored inside the 
patch data. Thus, wc would be able to send the patch back to its 
original location ONLY* This is not very versatile, especially since 
the Librarian will let uschange the patch number on the Librarian 
Page if we use the "P" variable. 

lo solve this problem, we'll use the first part of the data 
dump format as our SEND Initiate string, skip the original firs) 
four bytes of the stored patch, and then send the rest of the data 
So our SEND Initiate value is now: 

F0. 01.03. P 

and our SIN!) Data value, which skips past the first -1 bytes, is; 

(X.4.4). (X.40). F7 

Note thai we remembered to append theSF7 that earlier we 

chose not to store 

Since the first two bytes of both Initiate values are the 
same— SFO, SOI— let's define the PR ("Prefix") string variable to 
have this value, and use PR in both Initiate commands. They 
become: 

RECEIVE Initiate: PR. 00, P. F7 

SEND Initiate: PR. 03. P 

and our T8 protocol is now complete (see Figure tour) 

CASE STUDY: Oberheim Xpander synthesizer 

The Xpander's protocol is a bit more complicated than the 
I 8's because Xpander patches contain names that we can extract 
and display on the Librarian Page To build this protocol, we 
consult the "Oberheim Xpander/Matrix-12 MIDI Specification," 
part number 950038 from Oberheim 
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Using Gencric.Single to grab 1 patch, and reading the 
documentation, we find out the following information: 

• A single patch dump contains 398 bytes plus SF7. 

• I he patch name is found in bytes 382-398. 
•The format for requesting 1 single patch is: 

SFO "Begin system exclusive" byte. 
$10 Oberheim's manufacturer ID. 
$02 This is an Xpander. 
$00 Send me a single patch, please. 

The patch number (0-99). 
$F7 "End ol system exclusive" byle 



The format of a single patch dump is: 



SFO 
S10 
$02 
$01 
$00 



$F7 



"Begin system exclusive" byte. 
Oberheim's manufacturer ID. 
This is an Xpander. 
Here comes a patch. 
It is a single patch. 
The patch number (0-99) 
392 bytes of patch data. 
'End ol system exclusive" byte. 



Now we are ready to start writing the protocol. Since both 
the SEND and RECEIVE command will begin with the same 

hvtes, we define the PR I , T'retix ") variable once again this tune 
to be: 



F0. 10. 02 

On the RECEIVE panel, wc set the Initiate value to: 

PR. 0. 0. P. F7 

We now expect an entire patch dump of 398 (S18E) bytes to 
follow,endingwithanSF7,sowecanset the RECEIVE Data value 
to: 

(X.18E), F7 

For sending data, we use the same trick as in the T8 case 
study: skip over the first several bytes (containing the old patch 
number) and substitute our own in the SEND Initiate value. This 
value is: 

PR. 1.0. P 

We now skip the first 6 bytes of data (the header) and send 
only the 392 ($188) bytes of patch data itself, plus the SF7 we 
stripped off during the RECEIVE. 

(X.6.6).(X.188).F7 

Finally, let's tell the protocol how to locate the patch name. 
It is found in bytes 382-398 of the patch data. Thus, give Name 
Offset a valueof 382and Name Length a valueof 16. The Librarian 
will now extract and display the name of each patch as it is 
received 'sec figure five). 
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Figure Five Xpander 
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The formal of the SPX-W patch dump is the most compli- 
cated we've seen so for 

SFO ■Begin system exclusive" byte. 

S43 Yamaha's manufacturer ID 

n Use MIDI channel n. 

S7E This is some kind ol patch dump. 

$00 Together with the next byte... 

$58 this is the data length: 88 bytes. 

-LM 8332" t am an SPX-90 (there are 2 spaces). 

The patch number. 

32 bytes holding the 16-character patch name. 

46 bytes ot patch data. 

Checksum 
$F7 "End ol system exclusive" byte. 



Normally, we would be done now. However. Xpander 
patch names are stored in a particular manner that requires us to 
do a little more work. At the moment, only the first character of 
the patch name will actually be displayed on the Librarian Page. 
We shall solve this problem in Example "2 under HANDLING 
PATCH NAMES, below 

CASE STUDY: Yamaha SPX-90 
(or SPX-90II) digital effects unit 

(In order to transmit patch data from an SPX-90. you must first 
turn its MIDI THRU jack into a MIDI OUT. This isdoneby removing 
the lop cover (8 screws in alii and flipping switch number SWW5 to the 
"T" position. I 

In this protocol, we will use checksums and see an alternate, 
more reliable, method for handling the Data strings. 

To request a patch from (he SPX-90, the command is: 

SFO 'Begin system exclusive" byte. 

S43 Yamaha's manufacturer ID. 

$2n Use MIDI channel n, increased by S20. 

$7E Send me some kind of patch dump. 

_ LM 8332" I am an SPX-90 (there are 2 spaces). 

"M" Give me one patch dump. 

The patch number. 
$F7 "End of system exclusive" byte. 

By now, we are experts and can convert this into a RECEIVE 
Initiate string quickly, except for the line that says "Use MIDI 
channel n." Music-X provides (he N variable which always 
contains the number of the MIDI channel that we set on the 
Librarian Page. Once we add S20 to it, we're ready to type in the 
string: 

F0. 43. <20+n>. 7E. "LM 8332". "M", P. F7 

We will need some of these bytes again later, so let's store 
the first two bytes as the Prefix, and the two strings as Substring 
»1. This makes our RECEIVE Initiate value: 

PR, (20*n). 7E. <M,P. F7 



Our RECEIVE Data string needs to read 16 ($10) bytes ol 
header. 32 (S20) bytes of patch name, 4h ($2E>bytes of patch data, 
and I checksum byte. Using the same method as the previous two 
protocols, and ignoring the checksum issues for now, we would 
have a RECEIVE Data value of: 

(X.10MX.20MX.2F), F7 

or more simply: 

(X.5F). F7 

I lowever, this lime we will build more intelligence into the 

RECEIVE Data string by describing the forma tot the natch dump. 
This approach has two advantages: it checks the incoming data 
more closely, and it saves space by not storing the header bytes 
inside each patch. A small disadvantage is thai the patch library 
data is now more heavily dependent on the protocol; thus, it you 
plan to write your own programs to interpret Music-X library 
files, you may have a tougher time doing it 

There are 32*46* 1 (S4F) bytes of data after the patch num- 
ber. Once again ignoring the checksum, we write the RECEIVE 
Data string as follows: 

F0, 43. N. 7E. 0. 58, "LM 8332". "M". P. (X.4F). F7 

This is now an accurate description of the data we shall 
expect, so Music-X will complain if it reads any non-matching 
bytes Using our PR and Wl substrings, this becomes; 

PR. N.7E.0, 58. #1.P,(X.4F), F7 

Since everything before the (X.4F) is not captured by the X 
data variable, the header will not be stored inside each library 
entry. This fact is the reason for the advantages and disadvan- 
tages I listed earlier 

Now, let's handle the checksum byte. Yamaha forms its 
checksum value by adding all the bytes between "1 and (X.4E) 
inclusive, negating the value, applying a logical "and" operation 
with S7E. and truncating to one byte. This operation is nutated as 
(-K&7E.1). If the checksum received does no! match this value, 
Music-X complains. 
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To form this checksum, we surround the relevant bytes 
with curly braces. Thus, our finished RECEIVE Data string is: 

PR. N, 7E. 0. 58. 1*1. P. (X.4E)J. (-K&7F.1). F7 

Now it slimetobuildtheSFNDporlionofthcprotocol.VVe 
must remember that the header In tes and thechecksum have nol 
been stored in the library entry, so we must construct and send 
them manually. Well, guess what? We can use the same patch 
description we made for the RECEIVE Data string. There is no 
need for any SEND Initiate string in this case 

To save typing, we store the RECEIVE Data string as string 
»2, and then just put »2 in our RECEIVE Data and SEND Data 
strings. We are now done except for handling the patch name, 
which wediscuss in Example*) of HANDLINCPATCH NAMES, 
bclow(see figure six) 



ample, AZ means "all characters from 'A' to 'Z.' inclusive," and 
06 means "all characters from '0' to '6,' inclusive." You may also 
indicate a range of numeric values by using two hexadecimal 
numbers preceded by backslashes. 

Now look at your two-row table and pack your second row 
into ranges, as described above. In our example given, you wind 
up with this Character Map: 

\00\00.AZ,09.'" 

The first range, \00\00, is only one character long. It says 
that the value should be translated into 0. Is this detail neces- 

sary? Yes, because a Character Map is alwavs assumed to begin 
at zero II we used the Map 

AZ.09.?? 



Handling Patch Names 

It your instrument's patch data contains the name of the 
patch, Music-X can usually extract the name and displav it on the 
Librarian Page the instant that the patch is received. In order for 
this to work, you may need to specify some extra information: 

1 . WHERE the patch name is located in the patch dump: 

2 HOW LONG the patch name is; 

3. In WHAT FORM the patch name is encoded: the "Character Map." 

I he lirs! two items are pretty intuitive: after all, Music-X 
needs to know where the patch name begins and ends. This 
information is placed into the Name Offset and Name Length 
gadgets as explained in the manual. (Note: these two numbers 
must be in decimal, even though every other number in the 
Protocol Editor is in hexadecimal.) The Character Map, however, 
can be harder to understand, so I will now explain it in detail and 
include several examples 

Even though Music-X knows WHERE your patch name is, 
it may not know how to INTERPRET it. If your MIDI instrument 
uses N^CII and stores its patch name one character per byte, then 
no special interpretation will be necessary. However, suppose 
your instrument uses the values I through 26 to represent the 
letters 'A' through'/', values 27 through 36 to represent thedigits 
'0* through '9'. and 37 to to be a question mark character. This is 
NOT the ASCII code. So, you need to tell Music-X how to 
TRANSLATE between your MIDI instrument's internal code lor 
the patch name, and the standard ASCII code that Music-X (and 
most computers) use. This is done with a Character Map 

ToconstructaCharacIcrMap. pictu re the numbers through 
127 all lined up in a row. These are the numbers that your 
instrument uses for characters in patch names Beneath each 
number, write the character that the numberSHOULD represent 
to Music-X. The resulting two-row table is a Character Map 
Here's the Map for our example above: 



instead, then the value!) would be translated into'A.' I into 
'B.'etc. This is wrong— it's off by 1. 

The second range, AZ, says that the values 1-26 get trans- 
lated into the characters A' to 'Z.' The third range. 09. translates 

the values 27-36 into the characters O' through '9. 'The last range, 
??, is only one character long, and translates the value 37 into a 

question markcharacter. What happens to thevalues 38-127? The 
manual does not say, so I play it safe and specify that the) 
translate to themselves: 

\00\00.AZ.09.??.\26\7F 

Character Maps are versatile but have a few serious limita- 
tions. First of all. they cannot hand lecharacters that are not stored 
one per byte. For example, the Prophet VS synthesizer stores its 
name in tightly packed, 5-bit characters, which Music-X cannot 
translate. Second, Character Maps are insufficient if your 
instrument's internal character set is wildly unlike ASCII. For 
instance, if a synth has an internal character set like this 



5 6 
'M' '2' 



with characters placed arbitrarily in the table, there is no Charac- 
ter Map that can represent this translation. 

But, you cry, why can't we define a separate range for each 
character, containing ONLY that character, like this' 

AA.OQ.77,%%.RR.MM.22.". ... 

In theory, you can; unfortunately, the Char Map gadget can hold 
only 79 character! Thankfully, today's MIDI instruments are 
constructed around popular microprocessors that use ASCII. 
Perhaps a future version of Music-X will address these limita- 
tions 

I lere are some examples of constructing character maps. 



^16 1^ 
7 < 9 1 

Now that we have the table, how do we fill in the Char Map 
field on the Protocol Editor screen? This field contains a list ot 
RANGES OF CHARACTERS, separated by commas Tor ex- 



Example I: Sol Too Tricky 

Suppose your MIDI instrument uses values 28-36 for the 
digits T through '9', 37 for 0', 53-78 for small letters a-z, and 83- 
108 for capital letters A-Z. 
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\00\1B.19.00,\26\34.az.\4R52.AZ.\60\7F 

The rangesare 0-27 (SO-SIB) untouched, the digits 'V to '9/ 

thedigit'0'initsownr.inge.38-52(S26-S34)untouched,theletti'r> 
a-z, 79-82 (S4F-S52) untouched, and the letters A-Z. Tobesafc. we 
Spei iry that the remaining values 109-127 (S6D-S7F) translate to 
themselves 

Example 2: Those Pesky Zeroes 

The Oberheim Xpandcr's patch names ate stored in a way 
that causes problems for the Librarian. The patch name is 8 
characters long, but each character is stored in a two-byte Held. 
Thus, the name appears to have a zero stored in every other byte 
When Music-X reads the 16chara« ten a-- a name, and tries to print 
the name on the screen, it stops printing after the first character. 
Why? Because zero means "end of character string" in most 
Amiga programming languages, as all C programmers know. 
How can 1 print the entire patch name if ihe first /eroclfectivek 
cuts off the rest of the name? 

To remedy this, I used a Character Map to translate zeroes 
into space characters (ASCII S20). It leaves all other characters 
untouched. Here's theCharacter Map. assuming that the Xpander 
uses plain ASCII for the rest of its characters (which it does): 

\20\20.\01\7F 

Now the patch names arc displayed correctly, though a blank 
space appears after each of the 8 characters. We can eliminate the 
last space al least bv claiming that the name length is 15 instead 

ol 16. 

|ust for fun, let's modify our Char Map to translate capital 
letters into small letters. The Xpander uses only capital letters 
internally. On the ASCII table, capital letters are found in posi- 
tions 65-90 (S41-S5A), so we isolate this range: 

^20£0.\01\40.AZ,\5B\7F 

and then translate the letters to lower case: 

\20tfOAOl\40.az.\5B\7F 

Example 3: Sybbling al the Yamaha SPX-90 

The Yamaha SPX-90 digital effects unit stores its 16-charac- 
ter patch name in 32 bytes of data. F.ach character is represented 
as a two-byte quantity, with only the least-significant 4 bits used 
in each byte For example, suppose the first two bytesof the patch 
name are 4 and 5. In binary, these numbers are 00000100 and 
00000101 .Extract the least-significant 4 bits incachtogetOlOO and 
0101 . Paste them together to get 01000101 . This is Uhe number $45 
which is the character 'E' on the ASCII table. 

Anyway... can we make Music-X extract this patch name? 
I urning to the manual, we find that Music-X can indeed under- 
stand this "nybblized" data (a nybble is half a byte) by using the 
^ data variable (page 384). It can grab two bytes, extract their 
least-significant nybbles, and join them together into a single 
byte— exactly what we need. Hooray! 

Unfortunately, our success is short-lived. Music-X assumes 
that the first byte arriving is the least-significant, and the second 
is the most-significant. This is exactly the opposite of what the 



SPX-90 sends! In other words, in our $45 example above, Music- 
x will interpret mis as the number $54 (the letter T). Our method 

won't work. 

In fact, our method has a second problem ll we use the V 
variable to extract A) bbles, this changes the actual dala stored by 
Music-X,andtheretorealters the value oloui computed checksum 
(K variable)! In order to make this work, we would have to disable 

the checksum handling in our protocol, and treat Ihe checksum as 

an ordinary data byte 

As of this writing, I still have not managed to gel MUSIC-X 
to understand SPX-90 patch names. If anybody else can figureout 
a method, please contact me 

Conclusions 

I hope that this article has made protocols less mysterious 

for you. I've now written protocols for about 10 different instru- 
ments (including some fairly old synthesizers), and the process 
get9 easier each time. Don't be afraid to experiment: you can't 
break anything by writing an incorrect protocol. As with any 
computer dala. however, make sure to back up your patches in 
some other way before experimenting, in case \ OU accidentally 
overwrite something Good luck' 

ADDESDUM: A Few Bug You May Encounter (Music-X Ll) 

I encountered fl few hugs while using the Librarian and 

Protocol Fditor It you .ire editing an existing library's protocol, 

and you Load... a new protocol ami return to Ihe Librarian Page, 
the old protocol's name will still he listed under the " —Format— 
" label. In fact, if VOU now re-enter the Protocol Editor, the new 

protocol's name has been changed to Ihe old name (although the 
rest ol the new protocol is OK). 

It vou choose Load... in the Librarian, and then click on 
CANCEL in the requestor, your current library disappears From 
the screen (and is replaced b\ "\o Page") I consider this a bug 
because "CANCEL" should return the program to the exact state 
it was in before the requestor appeared. To bring back your 
library, use the Set Display command in the Edit menu. 

If you are m the Protocol Editor and you choose Load... or 
Save... from the File menu, sometimes the tile requestor's Dire< - 
tory gadget contains an incorrect value. This causes the n* 
" — Not a valid directory—" to be displayed in the requester. If 
you examine the directory name, you will find that the end of the 
directory name has been replaced by the PROTOCOL'S name' 

This happens if your directory name is longer than 32 characters, 
I have managed to put Music-X into an infinite loop (al- 
though its menu bar keeps working] bv choosing Load in the 
Librarian when there is already a library loaded. The problem is 
intermittent and may be related to the above directory bug. 
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AudioProbe 



by Jim Olinger 



Since the Amiga has the best built-in sound capabilities ol 
any personal computer, it's rather surprising how little attention 
Amiga sound programming has received This may be so because 
most people are visually oriented Humans are usually aware of 
what they are seeing. Sound is often subliminal. Hearing isa more 
subtle, primal sense. 

Or maybe it's just because it's so easy to play sampled 
sounds on the Amiga that few programmers have explored the 
alternatives, which call for diving deeply into Exec and I/O 
devices. Most games seem to use sampled sounds exclusively. 

There arc two general techniques for producing sounds 
with a computer; sampling and synthesis. Each has advantages 
and disadvantages. 

Sampling consists of playing back digitized sounds. The 
most realistic musical instrument sounds and most impressive 
sound effects are usually samples. The Amiga's advanced audio 
chips usually make sample playback a "fire and forget" proce- 
dure. The CPU can pass the sampled sound data and play 
instructions to the audio hardware and go on about its other 
business. 

Since samples are essentially audio recordings, a sample 
user faces all the problems of an audio engineer. The sound is 
usually recorded, digitized and then manipulated with sample 
editing software before it is ready to use. It's no wonder that most 
games include "sound designer" in the credits! Samples also tend 
to be large; 16 to 32K per sample is common. 

Synthesis is the process of manipulating relatively simple 
waveforms. The waves don't take up nearly as much memory as 
samples, but more attention from the CPU may be required. 
Synthesized sounds aren't as realistic as samples (although you 
might ask what a "real" phaser or hyperspace jump sounds like), 
but a synthesized sound might be perfect fora cockpit alarm or for 
an instrument in a musical soundtrack. 

Both sound generation techniques are valuable, and they 
are frequently used together. "Star Wars" is an excellent example. 
Every environment, such as Luke's planet, Obi-Wan Kenobi's 
home and the Death Star, had a characteristic background sound 
produced by simple analog synthesizers. Starship engines were 
derived from a recording of the Goodyear blimp. Darth Vader's 
voice was produced by radical filtering and electronic processing 
of James Earl Jones' voice. The unnaturally regular hissing of 
Darth'sbreath was another synthesizer sound. R2-D2's voice was 
a vvild mixture of human voices, puppy cries and synthesizers 
And so on. 

The accompanying program, AudioProbcl, was written to 
explore the application of analog synthesizer concepts to Amiga 
sound generation. It dynamically manipulates pitch and volume 



(the two simplest sound parameters). It is oriented toward pro- 
cessing simple waves, but it will also work with sampled sounds. 
In fact, most programmers will probably use the AudioProbe! 
techniques to increase the utility of individual samples by dy- 
namically modifying the sample to produce different sound 
effects. 

Before we get into the program, let's examine some basic 
synthesizer concepts and the Amiga audio hardware. 

Analog Synthesizer Basics 

The first electronic instrument was the Telharmonium, 
which was intended to send music to subscribers over telephone 
lines. It was invented in the 1890s. This service never took off, but 
the Telharmonium was the basis for the Hammond organs, 

developed in the 1930s. Several other electronic instruments were 
invented in the early decades of this century. 

"Classical" electronic music emerged after World War II It 
was based on manipulating sounds with the newly available tape 
recorders, and was actually closer to modern samplers than to the 
analog synthesizers which appeared a few years later 

The modern commercial synthesizer was developed in the 
late 1960s by Robert Moog. The first instruments filled a signifi- 
cant part of a room Sounds were "programmed" by connecting 
indh idual components with a tangle of patch cords. The early 
"Moogs" (practically a synonym for "synthesizer" at the time) 
were custom-built, temperamental, and very expensive. 

The first affordable synthesizer was the Mini-Moog (pro- 
duced from 1970 to 1981), which combined the large instrument's 
most often-used components into a suitcase- si zed package. It 
contained an organ-style keyboard, voltage-controlled oscilla- 
tors (VCOs).a noise generator, a mixer, a voltage-controlled filter 
( VCF), a voltage-controlled amplifier (VCA>, and two envelope 
generators, figure 1 is a block diagram of a generalized analog 
synthesizer voice, similar to a Mini-Moog A Mini-Moog could 
play only one note at a time. Modern synthesizers consist of a 
number of these voices, allowing several notes to be played 
simultaneously. 

Many musicians still prize their Mini-Moogs, which can 
produce sounds that are difficult to recreate on any other svnthe- 
sizer. 

The Mini-Moog sound sources are three voltage-controlled 
oscillators, which produce simple, but harmonically rich, wave- 
torms. and the noise generator, a circuit which creates a "hiss," 
like radio static. The number of complete wave cycles the oscilla- 
tors generate each second determines the pitch of the sound. 
Noise, being a set of random, non-repeating frequencies, has no 
distinguishable pitch. 
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Sound Synthesis Experiments in Modula-2 



The waves from Ihe VCOs .ire the basis of most instrument 
sounds while noise is useful for wind or surf effects, percussion, 
gunshots, or adding "breath" to flute sounds 

Figure 2 shows some common synthesi/er waveforms. 
Compare them to the acoustic instrument waveforms in Figure 3. 

The mixer combines the sound sources for processing by 
the filter and amplifier. 

The voltage-controlled filter is a "super tone control " It 
passes all frequencies below a certain "cut-off" point and re- 
moves all frequencies above that point. Filtering a waveform 
changes its shape. Since the waveshape determines the timbre of 
a sound, the filter is the primary timbre modifier. 

The voltage-controlled amplifier controls the final volume 
of the sound. 

One of the oscillators could be switched from voltage- 
controlled operation in the audio-range (20-20.1XX) Hertz) to low 
frequency output (0.2-20 Hertz) which could be directed to the 
VCOs to produce vibrato and/or to the VCF to create periodic 
timbre changes. 

The envelope generators output voltages which vary over 
time. One envelope genera tor is connected to the filter, allowing 
dynamic timbre variations. The other envelope generator con- 
trols the amplifier. 

Figures 4a and 4c are drawings of the waveforms produced 
by an organ and guitar playing three staccato (detached) notes, 
with high, medium ,and low pitches. Figures 4b and 4d are 
graphs of volume changes over the time the notes are being 
played and were obtained by connecting the highest volume 
points of the waveforms. These graphs are called "envelopes" 
and they represent the characteristic "shape" of an instrument 
note. 

An organ note starts plaving at full volume as soonasa key 
IS pressed. Continues plaving at that volume as long as the kev is 
held down, and ends abruptly when the key is released. A guitar 
note starts with maximum volume when Ihe string is plucked and 
the volume decreases smoothly and fairly quickly. 

A trumpet note (Figure's 4e and 4f) begins with a quick 
smooth volume increase, then drops back to a MckU level When 
the player stops blowing, the volume quickly, but not instantly, 
decreases to zero 

The envelope is an extremely important part of an 
instrument's characteristic sound. One wav of producing unique 
sounds is playingan instrument's waveform with the envelope of 
a different instrument. For example, a trumpet waveform played 
with an organ or guitar envelope will sound more like an organ 
or guitar then a trumpet. 



A trumpet envelope is the model for the ADSR (Attack, 
Decay. Sustain, Release), the most popular envelope generator 
(Figure 5). When a key is pressed, the output voltage climbs from 
zero to maximum at a rate controlled by the "attack time" control. 
After reaching maximum, the voltagedrops to the "sustain level" 
over the "decay time." It remains at the sustain level until the key 
is released and falls to zero over the "release time." 

The AudioProbcl program's ADSRs have an additional 
parameter, "sustain time." which controls the amount of time the 
envelope remains at the sustain level. 

Oscillators, filters, and amplifiers had been used in "elec- 
tronic music" for over 20 years when the Mini-Moog was devel- 
oped. They were everyday radio equipment. "Voltage control" 
was the key difference. Theearlier components had tobe manipu- 
lated manuallv. Forexample, a musician had to tum an oscillator's 
frequency knob tochange pitch. Playing a scale required record- 
ing each individual note and then splicing the tape. 

Voltage control changed all that. Voltage from the key- 
board controlled oscillator frequency. Voltages from the enve- 
lope generators shaped the response of the filter and amplifier. 
This gave the musician real-time control of pitch, timbre, and 
volume. 

The Mini-Moog and the ARP Odyssey, a similar synthe- 
sizer built by Moog's principal competitor, ARP Instruments, 
moved electronic musk from the recording studio into the world 



Figure One Generalized Synthesizer Votes 
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Figure Two Common Synthesizer Waveforms 




Of live performance. Most modern synthesizers still us*' the 
sound -genera ting techniques devised for these pioneering in- 
struments. 

Computer Synthesis 

Many analog synthesis concepts relate directly to computer 
synthesis. 

A computer can't produce analog waveforms directly. In- 
stead, a waveform is represented by a string of numbers, usually 
called a wavetable. To create a wavclable, one must divide the 
time axis of a graph of the waveform into equal segments. The 
points of the waveform at each time interval are called samples. 

To play a sound, thecomputer scans the wavetable, sending 
each sample to a digital-to-analog converter (DAC). The DAC 
output is sent to an amplifier, then to a loudspeaker. Tin- (re 
quency of the output waveform is determined by the speed at 
which the wavetable is scanned. 



Figure Three Acoustic Instrument Waveforms 




Analog oscillators contain circuits to produce a limited 
number of waveforms, such as sawtooth, square, and pulse 
waves. The raw waveforms are good for producing some pipe 
organ timbres, but are too harshly "electronic" for most musical 
applications. The filter is used to tailor the waveform to create 
more pleasing timbres. 

Computers usually don't have voltage-controlled filters to 
alter waveforms. Instead, the wavetable can be loaded with any 
waveform. One analog feature is lost: it's difficult to change a 
computer wavcformdynamically.Thiscan be done witha "double 
buffering" technique where a new wavetable is calculated while 
another wavetable i> being played. The second wavetable is then 
played while the first i> recalculated A detailed discussion ot 
double buffering will have to wait for another article. 

Voltage-controlled amplifiers can be computer-simulated 
by adjusting the amplitude of the samples in the wavetable or by 
controlling the digital-to-anatog converter's output level. The 
second method is preferred, if the hardware supports it. To 
minimize distortion, the wavetable should use the maximum 
available sample range and volume should be controlled bv 
adjusting the DAC output, Envelope generators, low frequency 
oscillators, and other controllers are simulated in software 

Amiga Audio Hardware 

The Amiga has four independent hardware audio channels 
("voices"). Each voice contains a direct memory access (DMA) 
channel, an eight-bit digital-to-analog converter and an ampli- 
fier. Channels0and3are connected to the left stereo output while 
channels 1 and 2 are connected to the right output jack. 

Complex audio effects can be created by using one audio 
channel to modulate the amplitude or frequency of another 
channel. We will concentrate on DMA playback of wavetables. 
Each audio channel is controlled by registers containing control 
data, the wavetable starting address, the wavetable length, the 
output volume, and the sample playback penod.The output 
volume ranges from (silent) to 64 (maximum). 

The playback period specifies the number of system clock 
ticks to wait before sending another sample to the DAC. One 
system tick is 0.279365 microseconds. The DAC requires 1 2-1 ticks 
(34.642 microseconds) to perform a conversion. Therefore, the 
minimum period value is 124 ticks. Since the frequency of a sound 
is the number of complete waveform cycles per second, the 
output frequency is determined by the wavetable length and the 
sample period. Note that frequency increases as period decreases. 
I lere is the equation for calculating the period: 
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P > period in system clock ticks 
L * wavetable length in samples 

'roquency in cycles per second (Hertil 



The audio software is implemented as a standard Amiga 
input/output device. It is controlled by standard I/O device 
commands, as described in Part I Chapter 4 (I/O) of the ROM 
Kenh-I Manual. 
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The AudioProbel Program 

AudioProbel consists of several modules, written in Bench- 
mark Modula-2. API Voices contains all the procedures for allo- 
cating, playing, modifying, and releasing voices. API Envelopes 
implements volume and frequency envelope generators for each 
voice. API Waves calculates several basic synthesizer waves, 
noise and user-specified waveforms. Noise is the basis for a large 
number of sound effects. The AudioProbel main program is 
primarily control logic and procedures for demonstrating fea- 
tures of the other modules. 

AudioProbel can read sampled sounds from disk, but it 
also generates simple synthesizer waveforms. It includes numer- 
ous procedures for experimenting with waveforms. The 
AudioProbel procedures for allocating, playing, stopping, and 
releasing voices are derived from the program in Lcn White's 
article "Digitized Sound Playback in Modula-2" (Amazing Com- 
puting. May 1989). 

The most important addition is the ability to modify the 
frequency and volume of sounds while they're being played. 
When I started writing the program, I expected this to be simple. 
It wasn't. An obvious way of changing frequency or volume is to 
play a voice, stop it, change the desired parameters, and start the 
altered voice. There is a distinct "pop" when the old voice is 
turned off. It's impossible to make smooth changes with this 
method, 



A voice is controlled by sending an I/O request to the audio 
device with the voice parameters in an lOAudio record. How 
about changing the parameters in this record while the voice is 
playing and sending another I/O request? This causes two prob- 
lems. First, it doesn't work. The frequency and volume stay the 
same. Even worse, the computer crashes when the voice is turned 
off. The "I/O" chapter of the ROM Kernel Manual warns, "I/O 
request blocks, once issued, must not be modified or reused until 
they are returned to your control by Exec." Exec doesn't release 
the request block until the voice has stopped playing. 

Each of the four voices is allocated by opening a communi- 
cations port, creating an I/O request, opening a copy of the audio 
deviceforthechannel. and sending an "allocate" command to the 
device. 

To control a playing voice, one must create another I/O 
request, with its own communications port and copy of the audio 
device. The "period" and "volume" fields of this "control" I/O 
request are set to the desired values and the "unit," "allocation 
key," and "data" fields are loaded with data from the I/O request 
block of the channel to be modified. This "change period/vol- 
ume" command is sent to the control I/O request's copy of the 
audio device. 

The device procedure "BeginlOO," rather than "DolO()," is 
used toplay and alter voices because "Begin! 0(),"unlike"DoIO()," 
doesn't reset the device flags in the I/O Request. 



Figure Four Instrument Volume Envelopes 
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Figure Five ADSR Envelope Generator 
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Operating AudioProbel 

Since AudioProbel is a program for experimenting with 
sounds, it has a simple character-based user interface to allow 
maximum flexibility (Figure 6). If AudioProbel is run from a 
console window, like the window created for the "Run Main 
Module" function of the Benchmark editor, the program is con- 
trolled by single keypress commands. If it is run from the Shell or 
CU, the "Return" key must be pressed after the command key to 
send the keystrokes to the program 

"Select Waveform" calls procedures which create simple 
wavetables. It also can load a sampled sound from disk. When a 
waveform is selected, it is played for two seconds at "Sample 
Volume". "Load Sample" is for "raw" samples. It will not work 
correctly with IFF formal samples. 



Figure Six AudioProbel Controls 
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Free sampled sounds can Iv found on public domain disks 
and bulletin boards. A number of companies listed in tin- "Music" 
section of AC's GuuU' to the Amiga sell disks of sounds. Some 
games, such as Falcon, have sound files which can be used for 
experiments. Of course, it's probably illegal and certainly unethi- 
cal to use other people's game sounds in your own commercial 
product. Numerousaudiodigiti/ers. >ome costing less than S100, 
an- available. Programs which will generate "samples" also exist. 
The AudioProbel "noise" waveform is anexampleof a computed 
"sample." 

Two ol the available waveforms, "Clarinet" and "Flute," 
were obtained by digitizing drawings ol the waveforms from a 
music book and reading evenly-spaced points with the co-ordi- 
nate feature of DeluxePaint HI. Wave sample values also could be 
determined by drawing the wave on graph paper. 

The waves "Sine," "Sine32," and "Sine64" demonstrate the 
differences in timbre between the same waveform represented by 
20, 32, and 64 sample values. 

"Set Frequency" controls the playback period. For short 
waveforms, frequency directly corresponds to the pitch of the 
output sound 1 lowever, since pitch is determined by both period 
and wavetable length, and the minimum period is 124 system 
clock ticks, long wavetables can't be played at high frequencies. 
For example, the length of the longest wavetable that can be 
played at 440 Hertz ("middle A") is 64 bytes. This length is 
sufficient for simple single-cycle waves. 

If the period is set to less then 1 24, theaudio hard ware won't 
have enough time to retrieve the next data sample and the 
previous sample will be reused. This produces unexpected audio 
effects. All the frequency- related procedures in the APlVoices 
module avoid this problem by setting any period values less than 
124 to 124 and writing an error message. I call this adjustment 
"period clipping." 

Sampled sounds, with wavetable lengths of 16K to 32K, 
contain many wave cycles, making the exact playback pitch 
difficult tocalculate. When playing long wavetables, a frequency 
under 1 Hertz should be used. Attempting to play a wavetable 
longer than 28,866 bytes at 1 Hertz, will cause period clipping. 

"Set Volume" adjusts the playback volume f rom O(silent) to 
64 (full). Both frequency and volumeare "base" values, whichcan 
be increased or decreased by the envelope generators. There are 
two independent envelope generators. One modifies frequency 
while the other modifies volume. 

"Modulation" is the maximum variation from the base 
value, expressed in percent. Positive and negative modulation 
amountsareallowed. The maximum volume modulationamount 
is -100% to +100%. A frequency modulation amount of +100% 
doubles the frequency, raising the pitch by one octave, while - 
100% halves the frequency, dropping the pitch by one octave. 
Frequency mod illations of several hundred percent are possible. 

"Attack Time," "Decay Time," "Sustain Level," "Sustain 
Time," and "Release Time" control the envelope shape. "Set 
Sample Frequency" and "Set Sample Volume" adjust frequency 
and volume for playing samples without using the envelope 
generators. "Set Sample Cycles" controls the number of times a 
sample will be repeated. These functions are used mainly for 
auditioning new samples. 

"Play Broken Chord" is a stereo demonstration. It starts 
each voice individually, building up to a four-note chord, then 
removes the notes individually. The envelope generators are not 
used 
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"Play Chord" playsa four-note chord. Frequency and vol- 
umecan be modified by (he envelope generators. If the frequency 
envelope is applied, the result is similar to a slide guitar chord. A 
major chord, containing the first, third, fifth, and octave notes of 
a major scale, is produced. The root note of (he chord is deter- 
mined by the "Frequency" parameter. 

"Play Note" plays a single note, controlled by the "Fre- 
quency" and "Volume" parameters and the envelope generators. 

The notes used in the chord experiments are computed 
using the relationships of (In- equal-tempered musical stale. In 
this system, the frequency of each note is the twelfth root of 2 
(1.059463) times the frequency of the previous note. Figure 7 
shows two octaves of notes in standard concert (uning, where 
"middle A" is 440 Hertz. The lowest scale note is set from the 
"Frequency" parameter 

"Play Siren" demonstrates volume and frequency changes 
without using the envelope generators. 

"Play Sample" plays the current waveform, controlled by 
the "Sample Frequency," "Sample Volume," and "SampleCycles" 
parameters This is primarily an "audition" function. The envfr 
lope generators are not used. 

Experiments 

Here are a few pointers bef.ire we get into the experiments. 

In the unlikely event (hat you haven't already hooked your 
Amiga's audio outputs to a stereo. 1 strongly recommend you do 
so before experimenting with AudioProbel . The distortion from 
the tiny amplifier and speakers in your video monitor can give 
you extremely misleading results. You will also miss the stereo 
effects if you use a mono monitor. 

AudioProbel is almost as complex as a Mini-Moog. which, 
to the beginner, is complex indeed. Many functions interact, often 
in ways which aren't immediatelv obvious. The Mini-Moog 
provides inslant feedback. When a switch is flipped or a knob is 
turned, something (usually) happens instantly. AudioProbel is 
controlled hy pressing keys to select menu items and typing 
numbers. This is more abstract than operating controls directly. 

Toavoid becoming disori- 



pitch indefinitely, based on the "Modulation Amount" param- 
eter (+100% modulation = 1 octave, +200"/.. modulation = 2 
octaves, etc.). The maximum frequency before period clipping 
(Hvurs is calculated by the equation: Maximum Frequency = 
28867 / WaveLength. The following table gives the frequencies 
loi the built-in AudioProbel waveforms 



Waveform 


Waveform 


Max Note 


Max Chord 


Name 


Length 


Frequency 


Frequency 


Sine 


20 


1443 


721 


Sine32 


32 


902 


451 


Sine64 


64 


451 


225 


Tnangle 


32 


902 


451 


Flute 


62 


465 


232 


Square 


20 


1443 


721 


Clarinet 


52 


555 


277 


Sawtooth 


32 


902 


451 


Noise 


4096 


7 


3 



ented, experiment with chang- 
ing one parameter at a time. Try 
many values of each parameter 
and many combinations of pa- 
rameters. Don't be afraid to try 
strange combinations. In syn- 
thesis, many impressive and 
useful sounds have been dis- 
covered by accident. 

If something unexpected 
happens, compare the relation- 
ships of all the elements. One 
common problem is envelope 
conflicts. If a sound has a long 
frequency envelope and a short 
volume envelope, the volume 
envelope will cut the sound off 
before the frequency envelope 
is finished 

The "Chord" and "Siren" 
functions have maximum 
pitchesan octave above the "Fre- 
quency" parameter ["Fre- 
quency" ' 2). Ihe Frequency 
Envelope ( ieneratorcan increase 



Figure Seven 
Equal-Tempered Scale 
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Setup: Set "Sample Volume" to 64. Select "Sawtooth" wave. 
While the "Audition" note is playing, adjust the volume on your 
stereo to a comfortable level. 

Waveform Resolution: Set "Sample Volume" to 64. Select 
the "Sine," "Sine32," and "Sine64" waveforms and compare their 
timbres. Notice that Sine32 and Sine64 are practically indistin- 
guishable while Sine has a distinct high-pitched whine added to 
the fundamental sound. This suggests that 32 samples is the 
optimum sample length for simple single-cycle waveforms. 

Waveform Timbres: Set "Sample Volume" to 64. Compare 
the timbres of waves with similar waveforms (see Figures 2 and 
3) such as "Sine32," 'Triangle," and "Flute" or "Square" and 
"Clarinet" (named "Bright Clarinet" in figure 3d). 

Stereo Voices: Select any waveform. Set "Frequency'' to 
avoid period clipping. Set "Volume" to 64. Play "Broken Chord". 
Notice how the individual notes appear in alternating speakers. 

Siren: Select any waveform. Set "Frequency" to avoid pe- 
riod clipping. Play "Siren." Be sure to try this with all waveforms, 
using numerous frequencies, including extremely low frequen- 
cies. 

Volume Envelope: Select the "Sine32" waveform. Set "Fre- 
quency" to 440 and "Volume" to 0. Set "Frequency Envelope- 
Modulation" to 0%. "Volume Envelope" parameters are Modu- 
lation = 100%, Sustain Level = 50%, Attack = 0.5, Decay = 0.5, 
Sustain^ 1.0 and Release = 0.5. Play "Note" and "Chord." Notice 
that the volume builds to full, drops back to half, sustains, and 
finally decreases to zero. Vary the Attack, Decay, Sustain, Sustain 
Level, and Release parameters and observe the change. Set "Vol- 
ume" to 16 and "Volume Envelope Modulation" to 75%. Play 
"Note." This time, the volume starts at 16 and builds. 

Frequency Envelope: Select Ihe "Sine32" waveform. Set 
"Frequency" to 1 10 and "Volume" to 64. "Frequency Envelope" 
parameters arc Modulation = 100%, Sustain Level = 50%, Attack 
= 0.5, Decay = 0.5, Sustain - 1.0 and Release = 0.5. Set "Volume 
Envelope Modulation" toO'u l'!,i\ "Note" and "Chord". Varythe 
"Frequency Envelope" parameters. Try "Frequency Modula- 
tion" = +200% and -200%. 

Volume and Frequency Envelopes: Vary the "Frequency 
Envelope" and "Volume Envelope" parameters with non-zero 
modulation amounts 
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Loony I lines: Select the "Sine' waveform N'l "I rcqueiuv 
to 1 10 and "Volume" to 0. "Frequency Envelope" parameters are 
Modulation ■ 200%, Sustain Level ■ 100%, Attack - 1.0, Decay = 
Sustain - 1.0 and Release ■ 0-5. "Volume Envelope'' param- 
eters are Modulation : 100%, Sustain l evel = 100%, Attack ■ 1.0, 
Decay 0.0, Sustain - 1.0 and Releases 05. Play "Chord". Does 
mis sound a bit like the beginning of a certain cartoon? 

\oise Experiments: \oise is a bask synthesizer waveform 
that is more like a sample than a simple waveform. The following 
experiments demonsirate some ot the ways muse can be used. 

)et Takeoff (heard from ground): Scle. i \oiso" waveform. 
lor a smgle-engine jet, set "Frequency" to 0.1 and "Volume" toO. 
"Frequency Envelope" parameters are Modulation = 200% Sus- 
tain I evel ■ 100%, Attack = 4.0, Decay ■ 0.0, Sustain ■ 12.0 and 
Release - 0.0. "Volume Envelope" parameters are Modulation ■ 
100%, Sustain Level = 100%, Attack = 4.0, Decay - 0.0, Sustain - 
6,0 and Release = 6.0. Play "Note " For a multi-engine Jet, set 
"Frequency" to 0.025 and play "Chord." Adjust any or all of these 
parameters to your own taste. 

To increase realism, play oneorrwo voices with the "Noise" 
waveform and add a high pitched whine by playing additional 
v ok. s with the "Sine" or "Triangle " waveforms This will require 

additional programming (see "Improvements"). 

Jet in Flight: Select "Noise" waveform. For a single-engine 
jet, set "Frequency" to 0.1 and "Volume" to 32 Set both "Fre- 
quency Modulation" and "Volume Modulation" amounts to 
zero. Control the time the sound plays by adjusting the "Sustain 
rune" tor either the Frequencv or Volume Envelope Generator. 
Play "Note." lor a multi-engine jet, set "Frequency" to 0.05 and 
play "Chord" 



One distinct problem with the AudioProbel envelope gen- 
erators is that they take over control of the program until the 
envelope cycle is complete. I his might be fine for short sound 
effects, but it could interfere with other activities, such as screen 
redraws, if a sound has a long envelope. One way of dealing with 
this problem would be to move envelope generator updates into 
the normal processing loop. Since the Amiga is a multi-tasking 
machine, a better solution would be to create a separate task to 
operate the envelope generators. 

Tlte End (Of The Beginning) 

This has been a brief introduction to sound synthesis \a 
with all skills, expertise in synthesis requires continued study 
and practice. Develop your ears. Listen to all the sounds around 
you and consider how they could be synthesized. Analyze the 
basic components ol a sound and determine how they can be 
manipulated to produce the effect you want. Be alert for happy- 
accidents. Many discoveries have been made on the waj to 
something else. 

An amazing and wonderful world of sound awaits you. 
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Improvements 

AudioProbel wasn't written as a music program, but music 

entry and editing capabilities could be added. However, al- 
though the Amiga has wry good sound-producing capabilities 
(foracomputer), you would probably get better results by buying 
a synthesizer. MIDI interlace, and sequencer software if your 
primary interest is music. 

AudioProbel doesn't provide the instant feedback of a 
Mini-Moogoi ARP Odyssey synthesizer, Thi> could be corrected 
by< I eating an Intuition-based control panel, which could be vcr\ 
useful for sound design experiments. 

Data for arbitrary waveforms i> created by manually deter- 
mining the sample values. I he wave could be entered by drawing 
it on the screen with the mouse. A procedure to save wa\edata 
to disk could be added. Procedures tor reading and writing IFF 
sound files could also be added. 

The ADSR envelope generator has the smallest number of 
parameters that can represent a complex instrument envelope, 

such asa trumpet envelope. It was popular with early synthesizer 

designers because it provided considerable flexibility with a 
minimum of components. With software envelope generators, 
we can have any number ol stages and levels. In (act, the 
API Envelopes module is written so that the only modifications 
required to change the number of envelope stages are changing 
the limits of the "Time" and "Level" arrays in the "EnvelopeRec 
data structure and adding statements to the "Set£nv«ope0 M 
procedure to initialize the additional stages 

I or simplitth . AudioProbel uses Ihe same waveform, fre- 
quent \ , volume, and envelope generator parameters for all four 

voices Since the hardware tor each voice is independent, all the 

controls lor each voice. .mid also be independent 
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/ earning Music With Synthesizer*. David Friend, Alan R. Pearlman, 
Thomas D. Piggott; Hal Leonard Publishing Corporation, 1974. 
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HAT HAS WM COLORS, 24-BIT FRAME BUFFER 
+GENLOCK+FRAMEGRABBER+FLICKER-ELIMINATOR 
+ PIP + VIDEO TITLER+3D MODELLING SYSTEM?} 

Introducing the 

IMPACT VISION 24 from GVP 

All-In-One Video Peripheral for the A3000 and A2000 




The All, 




IfyouYeinto video, IMPACT VISION-24 
is truly a dream come true for your 
A3000 or A2000. It is the first multi- 
function peripheral specifically 
designed for the A3000's video 
expansion slot. 

With the optional A2000 genlock slot 
adaptor kit, it also perfectly comple- 
ments and enhances the A2000. 
Check out these features, all packed 
on a single Amiga expansion board! 

► Separate Composite 
and Component Video 
IRC8+ Sync) Gertodts. 
RGB genJocfe opcntcs 
in ihcdiptal domain, 
tor digitally perfect 
production studio quality mixing: no color 
bleeding no ghflffinfl, no artifacts . J 

► 1MB Frame Butter. 1 fcpUy 24-bit 16 

million color images on your Amiga 
monitor. On a multi-sync monitor, you can 
even display 16 million coloi images tn 
rjon-inttdaced mode' 

► Hearome Framegrabber Drgrtner. ■ : 
grab and store iin standard 4096 or 16 
million color IFF format' any Iramc trom a 
"live" incoming RGB video source. 
Optional "RGB splitter' icquircd to grab 
incoming composite or S-VHS video 

► Rtcter-FJtmKatflr. Duplicates and enhances 
die UOOffiS display enhancer circuitry It 
even de-interlaces live 
external video! A must lot 
any A21XJ0 owner. Ask 
about our A2000 "genlock 
slot trade-up" program 
|in case your genlock slot 
is already used bv something less exciting! 

► amunaneous Component Video (RC8) Out. 
Composite Video Out and s-vhs Video Out. \ ,. 
anything vou can see on vour Amiga 
monitor can be' recorded on video tape 



traced 2-t-bit 



A/- 



including animations. ra\ 
images and mure**^^^ 

► PWurHrMWiri (PtP) Display. I revre 
resize, rescue and or reposition live i 
mg RGB video lust like anv wojubcncl: 
window at the double click oi a mouse v. 
the pressing ol .i "hot key" With a multi- 
sync all this can even be in rock steady 
dc- interlaced mode. Unique "reverse I'll' 
leaturc, even allows you to place a lullv 
luncthmal Amiga workbench |or other 
application 1 screen as a SCALE-ABLE Ishrunk 
down' and re-positH>nabJe window owi 
full-screen live video. 

pV To make sure you can take full and 
immediate advantage of even 1 feature of 
your new Impact Vision 24 video-station, 
we even include the following software 
with even- unit 

• Caiprt -4V24. An exclusive 
version ot the leading 
broadcast quality, 3-D 
modelling and rendering 

program. Use your imagination ^^^ Wl 

to model 3D, 16 million color, *W ^^^ 

-cenes Use your digitized video ^ itWC -d 

Images as textures to wrap around ' 
any obiect 1 The mind is the limit! 

• SCAIA -IRMaj. Easy-to-leam, video 
titling package complete with lots of 
special fonts and exciting special 
transition effects- Turn your Amiga 
into a character generator, 

• MACflOMHT W24. A 2D, 16 million color 

nam ,™i crafT that lets vou have lun wt 




pre-*- ■ .configurable! "hot key" Pa Ktf 
vate any feature. 

GVI'. wc wanted to make a nuior impact 
on the use o( the AJQ00/2O00 by profes- 
sional video enthusiasts. With the Impact 
Vision-?-! we have' 

For more information on how the tappet 
Vision 24 can have a maior impact on vour 
video productions, call us at 2^-337-8770. 



impacT visions 





creating or manipulating any 16 million 
eoloi 24-bit image 

Camp* Pant Provides full software 
control over all Impact Vision-24's numer- 
ous features. Use your mouse ot simph 



GREAT VAUEY PRODUCTS, INC. 
(.0(1 Clark Ave. King of Prussia. PA 19401. 
For more information or your nearest GVP 
dealer, call today. Dealer inquiries welcome. 
Tel. (215) 337-8770 • FAX (215) 337-9922 
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Valuable utility programs 
can save you time, monc> 
and, in the case of cata- 
strophic errors like hard 

drive failure, possibly 

months of work. 

Quarterback Tools - 
Recover Lost Files 
Fast and easy Reformats 

all types of disks - either 
new or old tiling systems - 
new or old Workbench 
versions Also optimizes 
the speed and reliability 
of both hard and (loppy 
disks Eliminates file frag- 
mentation. Consolidates 
disk space. Finds and fixes 
corrupted directories 

Quarterback - 

The Fastest Way 

To Back-Up 

Baddng-Up has never 
been easier. Or faster. 
Back-up to, or restore 



S/WEIT. 

MOVE IT. 

GET IT 
RACK. 



Back-Up . . .Transfer. . . Retrieve 

Quickly And Easily 

With Central Coast's 

Software For The Amiga 



i 



- 



• t 



1 1 









*&» 



from; floppy disks, stream- 
ing tape (Ami^aOOS- 
compatible), Inner- 
Connection's Bernoulli 
drive, or ANY Amiga DOS- 
compatible device. 

Mac-2-Dos 
& Dos-2-Dos - 
A Moving 
Experience 

It's easy. Transfer MS-DOS 
and ATARI ST text and 
data lilt's to-and-Irom 
Arnica DOS using the 
Amiga's own disk drive 
with Dos-2-Dos. and 
Macintosh files to-and- 
from your Amiga with 
Mac-2-Dos' Conver- 
sion options for Mac- 
2-Dos include ACS1I. 
No Ct inversion, 
MacBinary, PostScript. 
and Mac Paini co-and- 
from IFF file format 

•AV,/imo external 

Macintosh 'I'll'' 




Central Coast Software 

A Division Of New Horizons Software* Inc. 

206 Wild Basin Koad. Sum- 1(f). Austin. Texas 7 8746 
(512)328-6650* Fax (512) 328 1925 

QHmrtnim fcTtnA QHarWftktel Out - Dot mf "". -' Out <*> Mti itiiikmwlu 
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